New PropertySheet Design Document

Version: 1.0, April 2, 2003
Author: Tim Boudreau, Sun Microsystems/NetBeans
Following document describes the design of the new property sheet, according to the property sheet UI specification.
Document History:
[04/02/2003] : version 1.0: {Initial draft}
[04/02/2003] : version 1.1: {Minor edits, no content changes}
[04/03/2003] : version 1.0: {Addition of registerPropertyEditor method in PropertyEnv, per discussion with Jarda Tulach}


1. Overview

The existing propertysheet is very old AWT-style code reused from the first versions of NetBeans 2.0, circa 1998. The code is, at this point, extremely difficult to maintain, inefficient (for example, rebuilding its entire component hierarchy on certain types of property changes), and does not scale (creates components to represent properties that are scrolled off screen).

The plan in progress is to reimplement the propertysheet using the standard Swing JTable component, and deprecate or remove the aging, propertysheet-specific component classes which have proved to be major sources of bugs in the past.

For a graphical view of the planned design, see Figure 1.

2. Requirements

Renderers and editors

JTable's infrastructure is significantly different than that of the existing propertysheet. The key difference is that a JTable uses a "rubber stamp" approach to displaying its properties, reconfiguring a JLabel-like renderer to display different properties. This is also the source of JTable's scalability. When a cell must be edited, an editor component is inserted into the table.

In order to benefit from this design, it is necessary to create a rendering infrastructure supplemented by editors which will appear identical. Further, those editors must be able to respond to the mouse click or keystroke that in fact, instantiated them, to avoid the current implementations problem that two keystrokes or mouse clicks are often required where only one is logically needed. In order to satisfy this requirement, an interface InplaceEditor will be provided, which allows for forwarding of events to a newly created component, and a few state-determining methods to manage Swing issues.

To manage this, a JTable subclass will be used which intercepts keyboard and mouse events, checks its editing state, processes the events using the default mechanisms, then checks if its editing state has changed and forwards events as appropriate.


The JTable will be driven by a TableModel implementation specific to properties. The TableModel, in turn, will be driven by a model-within-a-model, PropertySetModel, which supplies properties and sets of properties. It is this model which will define what properties are displayed on the PropertySheet.

Expandable sets (tree-table look)

The current implementation uses a set of tabs, one per property set. The new property sheet will manage property sets primarily through expandable elements in the tree - a tree-table type view.

3. Performance

Part of the motivation for rewriting the property sheet is improved performance. The implementation will be written to use a minimum of objects (renderers and inplace editors should be singletons reconfigured on demand).

It is worth noting that a JTable has very different performance characteristics than the current implementation. The current implementation is composed of components each holding a reference to their assigned property. The new implementation will not hold such a cache, but rather go back to the property object to request property editor or other information as it is rendered. It may indicate performance problems in Node.Property, but this remains to be seen, and the performance of the prototype is adequate.

3. API Changes/Additions

  • It is necessary to un-final PropertyEnv - reusable, reconfigurable subclasses must be created for use when rendering - the alternative is creating vast numbers instances each time the table is repainted.
  • The registerInplaceEditor (InplaceEditor ed) method added to org.openide.explorer.propertysheet.PropertyEnv - New property editors that implement org.openide.explorer.propertysheet.ExPropertyEditor will be able to supply their own inline editors globally for all properties of a type. For example, if a module registers a property editor for the type java.util.Date, all properties will use that property editor, and thus the supplied InplaceEditor.
  • The InplaceEditor interface (see below) must be public - anyone using hinting to provide a custom inplace editor should implement this interface to avoid keyboard and focus issues. Legacy inplace editors will continue to work via an InplaceEditor wrapper.
  • PropertySet hinting for tab usage The UI requirements provide that some property sets should be expandable, and some displayed on their own tabs. Currently the FeatureDescriptor.getValue (String key) method is used by many Property objects to provide hints to property editors. Since PropertySet is also a subclass of FeatureDescriptor, a the same mechanism should be used to hint that a property set wishes to be displayed in some named tab other than the default view. By default, property sets providing no hint will be displayed in a common view, as expandable tree-table-like units.
If the future plan to repackage and separate the property sheet as a stand alone library (see below) is realized, it will be necessary to make the PropertySetModel public interface, to allow the existing property sheet class to supply a Node-aware implementation of the model.
Outline of the major portions of the implementation design
Fig 1. Outline of the major portions of the implementation design

4. Swing issues (with emphasis on focus problems)

There remain open focus issues in Swing, and focus behavior has been known to change even across minor releases - for example, there are some JDK 1.4.0-only focus fixes in the current codebase. A particular issue is that inplace editors will frequently be instantiated and then removed from the component, and the component which will receive focus subsequently, is not well defined, particularly when a popup such as a combobox editor has just closed.

The InplaceEditor interface

Because of the requirement that inplace editors be instantiated essentially transparently to the user, and that the property sheet return gracefully to the state it was in prior to closing (with focus shifting appropriately), some additional support is required in the InplaceEditor interface, to determine the conditions under which the property sheet is leaving the editing state.

The new inplace editors will implement the InplaceEditor interface - it will contain a number of methods for handling cases of known Swing issues, particularly focus issues, which cannot be handled any other way (for example, a combobox closing and focus being shifted to a random component or someplace unusable for the user). The InplaceEditor interface will be public.

Another aspect of the InplaceEditor interface is keystroke management. Some editors will want to consume keystrokes which the JTable will also consume. For example, by default, if you insert a JComboBox in a JTable as an editor, pressing the down arrow both selects the next item in the combobox, and changes the selection in the JTable, destroying the editor. Other components may have other collisions with JTable keymappings. The InplaceEditor interface allows an array of keystrokes to be provided, which should be ignored by the JTable while in the editing state.

Legacy custom inplace editors

The current infrastructure allows for custom inplace editors either by property editor hinting or via a deprecated API. This functionality appears to be extremely rarely used, however it should be supported.

New custom inplace editors will be supported by the same hinting mechanism as the current ones. For legacy inplace editors, a generic wrapper can be provided which assumes a worst-case scenario. There nonetheless may be behavioral issues with some legacy inplace editors.

5. Future plans


PropertyPanel is a visual component that displays a single property and can be used to invoke a custom editor, as well and has a number of different behaviors and states that can be invoked by non-normative editor hints. In the existing infrastructure, PropertyPanels are embedded in the current propertysheet in order to display properties.

In the opinion of this author, PropertyPanel is a single class that tries to do far too much, a known anti-pattern. It has been through one refactoring in an attempt to reduce its complexity, but remains a very complex component. Nonetheless, it is heavily used in NetBeans UI, and relies on a number of classes that could be deprecated or removed.

Following the property sheet rewrite, PropertyPanel should be rewritten too, where possible, reuse the rendering infrastructure from the new property sheet implementation - effectively inverting its relationship to the current property sheet.

Eliminating dependencies on Node.Property

The initial implementation of the property sheet will be heavily dependent on Node.Property. There is a basic contradiction in the design of PropertySheet vs. PropertyPanel: PropertyPanel is fully driven by PropertyModel, with wrapper models for Node.Property objects and arbitrary Object instances. It does not directly depend on Node.Property to do its work. PropertySheet, on the other hand, does require a dependency on the org.openide.nodes package. It should be possible to eliminate such dependencies and make the property sheet implementation also independent of this package. Since Node.Property and PropertySet both implement java.beans.FeatureDescriptor, it should be possible to make the new property sheet FeatureDescriptor driven rather than Node.Property driven. Further analysis is needed.

The initial implementation of the new propertysheet will have dependencies on Node.Property.

Separation of PropertySheet as a stand-alone library

If the above item can be accomplished, the next step would be to completely separate the property sheet package, such that it can be compiled and used as a standalone library. The existing PropertySheet class could be retained but delegate to a more generic property sheet class in the new library package.

7. Summary

For current status and individual tasks see Issue:

Please put questions or comments directly into that issue directly or at netbens developers mailing list.

Project Features

About this Project

openide was started in November 2009, is owned by Antonin Nebuzelsky, and has 92 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
Please Confirm