---

New AttachableAnchorShape API

Submitter: Trey Spiva

Type: Fast Track
Target Milestone: Netbeans 6.5

Short Discription

When an annotation is added to a connection they are usally represented as labels or children of the connection. The connection anchor shapes (arrowheads) are usally attached directly to the source or target widget. However sometimes the annotation needs to be between the Anchor widget (source or target) and the arrowhead.

The method AnchorShape.getCutDistance() specifies a point along the connection widget's path where the connection widget should stop painting. This feature was designed to stop rendering the connection at the edge of an anchor's shape. Custom AnchorShapes could be created to draw the shape at a distance away from the Anchor widgets. However, that would mean that users of the API would have to make a personal copy of the standard AnchorShapes to provide this functionality.

Solution

Since AnchorShape already as the ability to specify where the connection widget needs to stop rendering, the problem that needs to be solved is how to we allow AnchorShapes to be translated along the route of the connection without requiring all of the standard set of AnchorShapes to be rewritten? The best choice is to use an AnchorShape proxy approach. An AnchorShape can be used act as a proxy to another anchor shape. When the getCutDistance and paint methods are called, it can perform the neccessary math to translate the shapes location.

A second problem is how to determine the distance to translate the AnchorShape. In the case where an Annotation is placed between the AnchorShape and the Anchor Widget, the annocation may not be square, but instead a rectangle.

Therefore, when the connection is horizontal the distance would be different than when the connection is vertical. To solve this problem an interface called AnchorShapeLocationResolver should be used to resove the distance between the Anchor widget and the AnchorShape.

Dependencies

UML needs to be able to create qualifier labels that are placed on the ends of associations. The association will still have AnchorShapes that represent Aggregation, Composition, and Navigability. See the image above for an example.

Tracking Issue

Issue 133718

Change in Current Architecture

• An Inteface named AnchorShapeLocationResolver must be created in the package org.netbeans.api.visual.anchor.

public interface AnchorShapeLocationResolver
{
    public int getEndLocation();
} 

• Add three new methods to the AnchorShapeFactory class.

  /**
   * Creates a proxy AnchorShape that is used to adjust the location of an AnchorShape.
   * The associated AnchorShape will fit on the outside of the attached widget.
   */
  public static AnchorShape createAdjustableAnchorShape(AnchorShape shape, 
                                                        ConnectionWidget owner,
                                                        ConnectionEnd referencingEnd,
                                                        Widget attachedWidget)

 /**
   * Creates a proxy AnchorShape that is used to adjust the location of an AnchorShape.  
   * the location of the associated AnchorShape will be determined by a
   * AnchorShapeLocationResolver.
   */
  public static AnchorShape  createAdjustableAnchorShape(AnchorShape shape, AnchorShapeLocationResolver resolver)

When you use a resolver to move the anchor shape, other parts of the code may need to also be able to determine the location of the arrow head.

  /**
   * Creates a AnchorShapeLocationResolver that uses a widget to resolve the AnchorsShapes location.
   */
  public static AnchorShapeLocationResolver createWidgetResolver(ConnectionWidget owner,
                                                                 ConnectionEnd referencingEnd,
                                                                 Widget attachedWidget)

Impacted Interfaces.

The only API class that will be impacted is the AnchorShapeFactory. The factory will recieve three new methods.

Changes to apichanges.xml

        <change>
            <api name="general"/>
            <summary>New Attachable AnchorShape.</summary>
            <version major="2" minor="13"/>
            <date day="22" month="4" year="2008"/>
            <author login="tspiva"/>
            <compatibility addition="yes"/>
            <description>
                The new anchor shape can wrap an existing anchor shape and provide
                a new cut distance.  One example of when an attachable anchor 
                shape would be used is when a label on a connection widget is
                to be placed between the anchor shape and the related widget.
            </description>
            <class package="org.netbeans.api.visual.anchor" name="AnchorShapeFactory" link="yes"/>
            <class package="org.netbeans.api.visual.anchor" name="AnchorShapeLocationResolver" link="yes"/>
            <issue number="128348"/>
        </change>

Change Sets

• Source code Changes http://hg.netbeans.org/uml-meteora/rev/ce8e2aa62c28
• Additional Documentation http://hg.netbeans.org/uml-meteora/rev/88662e2022b5
• apichanges.xml http://hg.netbeans.org/uml-meteora/rev/bc1f5e49f641

Attachments