Extending Lienzo 1.0

From Emitrom

Jump to: navigation, search

Back to Index

Hand-point.png This page describes how it worked in Lienzo version 1.0. Significant changes were made in version 1.1. See Extending Lienzo for the current implementation.

To add a new Shape class:

  1. extend the class from Shape
  2. add new attribute names (if necessary)
  3. add new attribute types (if necessary)
  4. write Javascript wrapper class for new attribute type (if necessary)
  5. add getters/setters for its attributes
  6. implement draw method
  7. add support for attribute sheets
  8. add support for copying and Serialization (optional)
  9. add a Factory
  10. register Node type with NodeJSONRegistry

See Node Attributes


Example: Pear Shape

To illustrate the process we'll add a fictitious Pear shape. The Pear has two properties: "pearWidth", which is a double and "pearity", which is represented by the Java object "Pearity". The Javascript object that represents a "Pearity" has the following attributes: "flavor" (string), "leafCount" (number) and "leafColor" (color String).

Somehow these attributes describe the Pear's pearness and influence how the Pear will be drawn :-)

Extend class from Shape

public class Pear extends Shape<Pear>
     public static final ShapeType PEAR_SHAPE = new ShapeType("Pear");

"Pear" is used as the shape type identifier when serializing the shape.

Add Attribute name

The Attribute class is a type-safe, extensible enumeration of all possible Node attributes. When adding a new Shape class, it may be necessary to define new Attributes.

To add a new Attribute for PEAR_WIDTH and PEARITY we need to create two static variables (anywhere will do, we'll put them inside the Pear class):

public final static Attribute PEAR_WIDTH = new Attribute("pearWidth", "pearWidthLabel", "pearWidthDescription", 
public final static Attribute PEARITY = new Attribute("pearity", "pearityLabel", "pearityDescription", 

The first argument will be used internally as the attribute key. It is also used when deserializing the node to JSON.

The 2nd and 3rd value (label and description) values are placeholders for attribute sheets in Node editors. These values should be internationalized if you want to share your new class with international users.

The last argument describes what AttributeType the values of the new attribute have.

Add AttributeType

When adding a new Attribute, it may be necessary to add a new AttributeType (but try to use the existing AttributeTypes if possible.)

AttributeType is a type-safe, extensible enumeration of attribute types for all possible Node attributes.

Here are some of the built-in AttributeTypes:

AttributeType Java Type Javascript Type Notes
STRING_TYPE String String
NUMBER_TYPE int, Integer, double, Double etc. Number
BOOLEAN_TYPE boolean Boolean
COLOR_TYPE String String Any valid CSS Color String. See Color.
POINT2D_TYPE Point2D Object with attributes: x (Number), y (Number)
POINT2D_ARRAY Point2DArray Array with Point2D objects
SHADOW_TYPE Shadow Object with attributes: color (String), blur (Number), offset (Number)
DASH_ARRAY_TYPE DashArray Array of Numbers
LINEAR_GRADIENT_TYPE LinearGradient Object with attributes: start, end, colorStops and type="LinearGradient" start and end are Point2D objects.
colorStops is an Array of Objects with stop (Number) and color (String) attributes.
PATTERN_GRADIENT_TYPE PatternGradient Object with attributes: image (TODO), repeat (see enum FillRepeat) and type="PatternGradient"
RADIAL_GRADIENT_TYPE RadialGradient Object with attributes: start, end, colorStops and type="RadialGradient" start and end are Objects with x (Number), y (Number) and radius (Number) attributes.
colorStops is an Array of Objects with stop (Number) and color (String) attributes.
DRAG_BOUNDS_TYPE DragBounds Object with attributes: x1, y1, x2, y2 (all Numbers)
FILL_TYPE Color, LinearGradient, PatternGradient or RadialGradient see above
STROKE_TYPE String String (same as COLOR_TYPE)

Each enumeration has its own type (the internal value is the string value obtained with EnumWithValue.getValue):

AttributeType Enum Javadoc
LINE_CAP_TYPE LineCap Hand-point.png Javadoc
LINE_JOIN_TYPE LineJoin Hand-point.png Javadoc
DRAG_CONSTRAINT_TYPE DragConstraint Hand-point.png Javadoc
TEXT_ALIGN_TYPE TextAlign Hand-point.png Javadoc
TEXT_BASELINE_TYPE TextBaseLine Hand-point.png Javadoc
COMPOSITE_OPERATION_TYPE CompositeOperation Hand-point.png Javadoc
ARROW_TYPE ArrowType Hand-point.png Javadoc

Here is an example for adding the new AttributeType for the "pearity". Pearity will need a custom validator. This is used during deserialization.

public static AttributeType PEARITY_TYPE = new AttributeType(new PearityValidator());

Write Javascript wrapper class

To represent the "pearity" type, we would probably write a Java class called "Pearity". It's a wrapper around a Javascript object. We normally create a separate class that extends JavaScriptObject (PearityJSO in this case.) See the Lienzo source code for examples on how to implement these classes (e.g. DragBounds).

public static class Pearity
  private final PearityJSO m_jso;

  public Pearity(PearityJSO jso)
  { ... }

  public final PearityJSO getJSO()
     return m_jso;

  public static final class PearityJSO extends JavaScriptObject
  { ... }

Add getters and setters for new attributes

    public Pear setPearity(Pearity pearity)
        if (null == pearity)
            getAttributes.put(PEARITY.getProperty(), pearity.getJSO())

        return cast();

    public Pearity getPearity()
        JavaScriptObject jso = getAttributes().getObject(PEARITY.getProperty());
        if (null == jso)
            return null;
            return new Pearity(jso);

    public Pear setPearWidth(double pearWidth)
        getAttributes().put(PEAR_WIDTH.getProperty(), pearWidth);

        return this;

    public double getPearWidth()
        return getAttributes().getDouble(PEAR_WIDTH.getProperty());

Implement draw method

The draw method in the Shape class should assume that the Transform related attributes have already been applied to the Context2D.

Here is the draw method for the Circle class. Note that it draws the center at (0,0) because the Transform related attributes (such as X and Y) have already been applied to the Context2D.

    public void draw(Context2D context)
        context.arc(0, 0, getRadius(), 0, Math.PI * 2, true);

If the new Node class is a type of ContainerNode, it should also draw its children here. See the source code for Group.draw() for an example. (Usually you don't need to derive from ContainerNode. Just use a Group with child nodes instead.)

Add support for attribute sheets

Add this to the Pear class:

    private static final List<Attribute> s_attribute_sheet     = makeAttributeSheet();
    private static final List<Attribute> s_required_attributes = makeRequiredAttributes();

    private static final List<Attribute> makeAttributeSheet()
        ArrayList<Attribute> list = new ArrayList<Attribute>(Shape.getAttributeSheetForShape());
        return Collections.unmodifiableList(list);

    private static final List<Attribute> makeRequiredAttributes()
        ArrayList<Attribute> list = new ArrayList<Attribute>(Shape.getRequiredAttributesForShape());
        return Collections.unmodifiableList(list);

    public static final List<Attribute> getAttributeSheetForPear()
        return s_attribute_sheet;

    public static final List<Attribute> getRequiredAttributesForPear()
        return s_required_attributes;

Note that optional attributes should not be returned by makeRequiredAttributes.

Add support for copying and Serialization

By adding support for Serialization to JSON we get a copy method for free. copy simply serializes to JSON and then deserializes the JSON into a new object.

Add type Validator

All we need to do is add validators for the new AttributeTypes, in this case PearityValidator which was used by PEARITY_TYPE above.

public class PearityValidator extends ObjectValidator
    public PearityValidator ()

        // the 3rd parameter indicates whether the attribute is required
        addAttribute("flavor", StringValidator.INSTANCE, true);
        addAttribute("leafCount", NumberValidator.INSTANCE, true);
        addAttribute("leafColor", ColorValidator.INSTANCE, true);

Add a Node Factory

    public static class PearFactory extends NodeFactory<Pear>
        public PearFactory()
            super(Pear.getAttributeSheetForPear(), Pear.getRequiredAttributesForPear());

        public Pear create(JSONObject node, ValidationContext ctx)
            return new Pear(node);

Register Node type with NodeJSONRegistry

And register the factory with NodeJSONRegistry:

NodeJSONRegistry registry = NodeJSONRegistry.getInstance();
registry.addNodeFactory(Pear.PEAR_SHAPE, new Pear.PearFactory());
Personal tools