The NetBeans Debugger Interface
General Table Behavior

For: NB 3.4 Debugger Interface
Author: David-John Burrowes
Revision History: in CVS Repository

Contents:


Introduction

With NetBeans 3.4, the views shown in the Debugger Window will switch to using a tree-table component to represent their data, rather than using a tree component.

This document defines the generic interface details of this component. By "generic", this means this doesn't make specific reference to any particular view (e.g. sessions, threads, breakpoints, etc.), but instead documents behavior that should be common to all.

User View

User Model

The user of these components should be encouraged to think of the component as representing a list of objects, where each row in the list represents a single object and each column in the list represents a property of the object. Generally, these properties correspond to the properties that would be shown in the corresponding NetBeans property sheet for the object. The user may choose to show or hide columns in order to see the information they want.

In some cases, the objects in the list may contain "children" objects which can be viewed by expanding the parent object.

List

Appearance

The following illustration shows a list:

Headers

Change Visible Columns Button

Scrolling List

Behavior

Selection

Each list may allow zero or one row to be selected, or it may allow zero, one or more (discontinuous) rows to be selected.

A row may be selected by clicking on it (or with shift-click or ctrl-click for contiguous and discontinuous selection), or with standard JLF keyboard actions. [Note: it is not possible to do discontinuous selection with the keyboard using JTable in at least JDK 1.3].

If the user right-clicks on a part of the table body which does not contain a selection, then there is a row under the pointer it should be selected, otherwise any selection highlight in the table should be removed. (Pressing Shift-F10 to display the contextual menu will not affect the selection).

If the table allows multiple rows to be selected, then it must support the Select All action (Ctrl-A) to allow the user to select all the rows at once.

Column Movement

Columns (including the identifier column) may be freely rearranged.

The arrangement of the columns should be persisted across runs of the IDE. When possible, these should be preserved when columns are hidden and shown (though, this isn't always possible. See below). [not done in 3.4]

Columns may be rearranged with the mouse, using the standard JLF gesture: click and drag on the column header. With the keyboard, the user must move the focus to a cell in the relevant column, and then use commands provided in the contextual menu (see below). Note that if the table contains no rows, there will not be any keyboard focus and it will be impossible to reposition the columns.

Resizing

Individual columns may be resized (made wider or narrower). Individual columns may choose to define minimum and maximum sizes if it seems appropriate. In general, the minimum width for a column should be either one letter or an icon.

These widths should be persisted across runs of the IDE, and should be retained even when columns are hidden or shown. [not done in 3.4]

With the mouse, the columns should be resized in the standard manner provided by JTable.

[Optional for 3.4] To resize the columns from the keyboard, use the command from the contextual menu described below.

Sorting

The contents of list is always sorted by the contents of one column. This column does not necessarily need to be visible. When a column is sorted, the contents of the list should be kept "stable" (which means that if row A was before row B, then when the table is resorted on a new column that both rows have the same value in, then A will always remain before B).

The list may be sorted on a column by clicking on the header of that column. This will always put that column in an ascending sort order. Clicking on the column again toggles the sort order (ascending to descending to ascending...). The list may be sorted with the keyboard using menu commands on the contextual menu (see below).

When the objects in a list have children, then the children rows should be sorted only within the scope of the parent object.

Contextual Menu

The user may always display a contextual menu for the list. Most of the items that may appear in this menu apply to the selected object(s) in the list. However, there is always as "List Options" item which contains commands and settings which apply to the list, rather than the individual objects in the list. If there are no selected objects in the list, then the contextual menu will only contain the "List Options" item, and any object-creation items (e.g. Add Watch...). In other cases, this item always appears above a separator and the Preferences item.

The following two illustrations show the standard contents of the List Options submenu.

Notes:

Extensibility

All views must have these submenu items [though, a list that doesn't allow sorting should not have the Sort By column]. Individual views may, however, add other list-related items to these menus.

Object Row

Appearance

In general, the contents of each row are drawn in the same way they are in JTable, with these differences:

Behavior

Any action will apply to all the selected columns.

Showing Properties

If the user chooses Properties from the contextual menu, a standard NetBeans dedicated property window should be shown displaying all the properties for the selected objects.

Copying Information

[Optional for 3.4] the "Copy" command should copy a textual (tab delimited) representation of the selected row(s) of the table.

Editing a Cell

Most cells in these lists will be read-only. For those that may be edited (e.g. the value field of a variable), the user should be able to use standard Swing gestures to start editing the contents of the cell that contains the keyboard focus. (as mentioned above, when this is done, the selection in the list should be drawn in a disabled color since it would no longer be the active selection).

[Optional for 3.4] I would expect that editing a cell would behave essentially just like editing a value in a property sheet. That is, the cells contents would be editable, and if you could type into the cell, there would be a "..." button which would display a dialog where you could edit longer values, and perhaps have a more structured editor of some sort.

Expanding a Row

If a row has children objects, then a double click on any non-editable column will expand or collapse the children. Additionally, clicking on the turner will have the same effect. [this turns out to be more complex, since doubleclick in some lists must mean to make the item current. this needs to be revisited]

This can also be done with the contextual menu.

Contextual Menu

When a contextual menu is displayed for one or more rows in the table, menu items relevant to those rows are shown in the menu.

As an informal guideline, actions which act directly on the objects (Delete, Suspend, etc.) should be listed first in the menu, commands which use the object in an indirect manner (e.g. an "Add Breakpoint in Method" action on a stack frame object) should be listed next, and any actions which create new objects should be listed last in the menu. [This isn't completely true, since the first item should be the action that will be taken on a double click].

Note that if a row has children objects, an item in the contextual menu should be "Expand {item}" or "Collapse {item}". "{item}" should be replaced by the name of the kind of row (e.g. Thread, Thread Group, Variable, etc.), and the name should be "Expand" or "Collapse" based on the action being taken.

Change Visible Columns Dialog

The Change Visible Columns dialog is a modal window which provides a list of all the possible columns that may be shown in a list and to allows the user to pick which columns to show and which to hide.

Appearance

Some notes about this dialog:

Behavior

Column Management across Debugger Engines

Each debugger engine must define the a set of columns which should appear in each view. This should be as small a set as possible, and in general should be the same as the minimal set defined in the specifications for each view. During a run of the IDE, whenever a debugger engine first displays information in a view, the debugger core should examine the set of columns defined by that debugger engine and compare them with the columns already showing in the view. If the debugger engine defines a column which should appear in the view, and that column is not visible and hasn't been previously hidden by the user, then the debugger core should automatically add that column to the view. This column should remain until there are no longer any sessions using the debugger engine, at which point they should be automatically removed. This feature is provided because we recognize that debugging some kinds of things genuinely requires some information to be meaningful. However, debugging engines should exercise tremendous restraint when adding columns to the base set since it violates the goal of presenting a truly unified debugging interface.