---

Visual Library Resource Table API Review

Submitter: Trey.Spiva@Sun.COM

Type: Fast Track
Target Milestone: Netbeans 6.5

Short Description

This addition to the Graph Library API is trivial. The request is to add a resource table construct to the graph library. The resource table will allow for a central location for properties like font, color and paint objects. The resource table will help enforce an application's look and feel. When a property is updated in the resource table, all interested widgets will be notified of the change. The notification allows widgets to update when a resource property changes.

Dependencies

The UML graph module depends on this feature to support allowing users change the color and font of a node.

Tracking Issue

Issue 134265

Change in Current Architecture

A ResourceTable will be added to the package org.netbeans.api.visual.widget. The Widget class will have two new methods that are used to specify the resource table that is used by the widget getResourceTable() and setResourceTable(ResourceTable). If a resource table has not been associated with a widget, the parents resource table is retrieved.

/**
* Retreives the widgets resource table.  If the widgets resource table is 
* not set then the widgets parent resource table it retrieved.
* 
* @return The resource table.
*/
public ResourceTable getResourceTable() {
        
   ResourceTable retVal = resoruceTable;
        
   if((retVal == null) && (getParentWidget() != null))
   {
      retVal = getParentWidget().getResourceTable();
   }
        
   return retVal;
}

The widget will have three additional methods that are used to set a widget's property via the resource table. The name of the methods are setBackgroundFromResource, setForegroundFromResource, and setFontFromResource. When a property is set from the resource table, the widget also adds a listener to the table to update when the property value changes. This approach keeps the graph library from having to retrieve the property value during the paint cycle. Therefore, the paint performance remains the same.

Three notify methods have been added to the widget. These methods are used to notify derived classes when a property has changed. The three new notify methods are notifyBackgroundChanged, notifyForegroundChanged, and notifyFontChanged.

The BorderFactory has been modified to allow users to create borders that use a ResourceTable to set the color properties.

Use Cases

1. Need to enforce a look across all widgets
2. Need to allow the user to change the properties of a node class and have the change propagated across the scene.
3. Need to allow the user to override the scenes properties on an individual node or connection basis.

apichanges.xml

<change>
            <api name="general"/>
            <summary>New Resource Table.</summary>
            <version major="2" minor="14"/>
            <date day="29" month="4" year="2008"/>
            <author login="tspiva"/>
            <compatibility addition="yes"/>
            <description>
                The resource table will allow for a central location for
                properties like font, color and paint objects. The resource 
                table will help enforce an applications look and feel. When a 
                property is updated in the resource table, all interested
                widgets will be notified of the change. The notification allows 
                widgets to update when a resource property changes.
            </description>
            <class package="org.netbeans.api.visual.widget" name="ResourceTable" link="yes"/>
            <class package="org.netbeans.api.visual.widget" name="Widget" link="yes"/>
            <class package="org.netbeans.api.visual.border" name="BorderFactory" link="yes"/>
            <class package="org.netbeans.api.visual.border" name="Scene" link="yes"/>
            <issue number="128348"/>
        </change>

Change Sets

The history of source file changes

• Initial code check in: http://hg.netbeans.org/uml-meteora/rev/efdf18b14e58
• Fixed Null Pointer Exception: http://hg.netbeans.org/uml-meteora/rev/37ecc081b24f
• Made changes to the resource table: http://hg.netbeans.org/uml-meteora/rev/d2aaaa67127e
• Made changes to use Object type: http://hg.netbeans.org/uml-meteora/rev/6d10af940260
• Added a getParent method to the resource table: http://hg.netbeans.org/uml-meteora/diff/410877ffed00/api.visual/src/org/netbeans/api/visual/widget/ResourceTable.java
• Fixed issues with calling setXXXXFromResource before parent structure is set: http://hg.netbeans.org/uml-meteora/rev/ba3c395b0532
• Modified the apichanges.xml: http://hg.netbeans.org/uml-meteora/diff/b1f8bce25603/api.visual/apichanges.xml