The NetBeans Debugger Interface
General Table Behavior

For: NB 3.4 Debugger Interface
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

  • When the table is sorted by a column, the name in the header should be drawn in bold text.
  • An icon is shown next to the bold text to indicate whether the column is sorted ascending or descending (pointed up means ascending).
  • If a column header is truncated, it should end with an ellipsis (or a locale-specific annotation).
  • If the mouse pointer "hovers" over a truncated column header, then a tooltip should be shown with the full name of the column.

Change Visible Columns Button

  • The button is used to display a dialog to control which columns should be shown in the table.
  • This button is not accessible from the keyboard. However, an item in the contextual menu for the table provides access to the same dialog.

Scrolling List

  • Rows are drawn with a Secondary 2 color horizontal grid line.
  • Horizontal scrollbars are never shown. The set of columns is always stretched or condensed enough so that all may be shown in the available space.
  • The vertical scrollbar is always visible.
  • One column (the "identifier column") in each table must contain a meaningful identifier for the row, and this may contain an icon representing this object and if it has children it may also have a turner.
  • The selected row(s) are drawn with the standard JLF selection color
  • One cell in the selection should show the keyboard focus
  • If the user starts to edit a value in a column of a row, the row selection should not be drawn.
    • [Optional for 3.4] If we want to anticipate what NetBeans may do in the future, the selection should be drawn in the corresponding JLF Secondary color when it doesn't contain the keyboard focus.
  • If the list contains no rows, then the component should show a message explaining this in Secondary 2 color and centered both vertically and horizontally in the table body.

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:

  • [Optional for 3.4] The Column submenu has commands "Move Left" and "Move Right" which move the column with the current keyboard focus left or right one position in the list. This is an accessibility feature which should eventually be provided by the JDK, and so supporting it here is a low priority.
  • [Optional for 3.4] The Resize command should display a dialog box which will ask the user to type in a new width, in pixels, for the column that currently contains the keyboard focus. This is an accessibility feature which should eventually be provided by the JDK, and so supporting it here is a low priority.
  • The first group of items in the Sort By menu list all the columns shown in the list, and always indicate which column the list is sorted on. That column does not necessarily need to be visible. When the sort column is changed, the new one should initially be sorted in an ascending order.
  • The second group of items in the Sort By menu specify whether the current table is sorted ascending or descending.
  • The Change Visible Columns item displays the same dialog that appears when the Change Visible Columns button in the table is clicked.
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:

  • Because there are no vertical grid lines shown in the table, the cell renderers must be set up to draw their contents one pixel away from the horizontal edge of the cell.
  • Each column should be justified appropriately for its data type (e.g. columns displaying strings may be left justified, while columns containing numbers may be right justified). This justification may vary based on the locale, and so this should probably be able to be specified in a localization file.
  • If the contents of a cell are wider than the cell is, the contents should be truncated and an appropriate marker (an ellipsis in most locales) should be shown at the end. [not done in 3.4]
  • If the pointer hovers over a truncated cell, a tooltip should be shown displaying the untruncated contents of the column. [not done in 3.4]
  • If an object has no value corresponding to one of the columns in a list, no value should be shown in that column.
  • I suspect that as the user moves the keyboard focus across the row, a screen reader should read "contents is the property of name" (e.g. "Running is the status of com.example.Ted's"). This order was chosen to allow the user that is oriented to get the information they need fastest, while still allowing the disoriented user to get full orientation information. A template for this should be provided in the localization bundle so other locales can arrange the elements in a meaningful way.
    If the list is sorted on this column, text to the effect "This is the sorted column" should be appended to the text just described.

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:

  • The title bar should list the "object" being modified (the view ("Breakpoints" or "Sessions" etc.), in this case) followed by a hyphen and then the name of the action being performed (this is in line with the JLF Advanced Topics guidelines).
  • The list of columns should just be a simple list of checkboxes, where the labels have the form column name: very short description.
  • If there are more items in the list than can fit on the screen, the checkboxes should be put into a scrolling list.
  • The first item in the list should be the identifier column and it should always be checked and be disabled, since the user should not be able to hide this column
  • Mnemonics may not be used here for the same reason they aren't use in the contextual menus in NetBeans: the contents are unpredictable enough that mnemonics aren't reliable.
  • All the columns that are visible in the list should be checked when the dialog is first shown.
  • The columns should be listed in an alphabetical order. [excluding the first item, since it may not be repositioned]

Behavior

  • When the dialog is shown, the keyboard focus should start on the topmost enabled checkbox, and pressing tab should progress down the list from top to bottom then to the buttons at the bottom, then to the description at the top and then repeat.
  • When the dialog is dismissed, all the columns which were checked by the user should be shown in the table, and unchecked items should not be shown.
  • If the user has reordered the columns, then it may not be possible to determine where a column should be shown in the list when the dialog is dismissed. I think the following heuristic will work most of the time: each column should have a natural "left neighbor" (as specified by the first debugger that provides the column). If the user reorders the columns, and then shows some new columns with this dialog, each will appear to the right of its "left neighbor" (if that column is not showing, then that column's left neighbor, and so on. This assumes that the identifier column is always the leftmost item provided by each debugger.

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.

Project Features

About this Project

ui was started in November 2009, is owned by Jiří Kovalský, and has 37 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20131025.e7cbc9d). © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
 
 
Close
loading
Please Confirm
Close