documentationfor yFiles for HTML 2.6
The Scene GraphVisualizing Arbitrary Objects

The IVisualCreator

IVisualCreator provides the framework for creating visualizations of objects that are displayed in a CanvasComponent. The methods createVisual and updateVisual manage the actual visual representation — an object of type Visual. The createVisual method is called when the object’s visualization should become visible for the first time. In the subsequent redrawing process of HTML5, the updateVisual method is called with the Visual instance of the previous rendering step. In this method, the Visual instance’s values (e.g. the position) can be updated instead of creating a new Visual instance.

The following example shows a custom IVisualCreator implementation which displays a rectangle with given dimensions.

A custom IVisualCreator implementation
// A custom visual creator implementation
// which renders a rectangle
class RectangleVisualCreator extends BaseClass(IVisualCreator) {
  // creates a new instance which renders the given rectangle
  /**
   * @param {!Rect} Rectangle
   */
  constructor(Rectangle) {
    super()
    this.Rectangle = Rectangle
  }

  // Creates a visual
  /**
   * @param {!IRenderContext} context
   * @returns {?Visual}
   */
  createVisual(context) {
    const rect = window.document.createElementNS('http://www.w3.org/2000/svg', 'rect')
    rect.setAttribute('fill', '#6699CC')
    this.setLayout(rect, this.Rectangle)
    return new SvgVisual(rect)
  }

  // updates the layout
  /**
   * @param {!IRenderContext} context
   * @param {!Visual} oldVisual
   * @returns {?Visual}
   */
  updateVisual(context, oldVisual) {
    if (!(oldVisual instanceof SvgVisual)) {
      // If the visual is not of the expected type create a new one
      return this.createVisual(context)
    }
    const rectangle = oldVisual.svgElement
    this.setLayout(rectangle, this.Rectangle)
    return oldVisual
  }

  /**
   * @param {!SVGElement} rectangle
   * @param {!Rect} layout
   */
  setLayout(rectangle, layout) {
    rectangle.setAttribute('x', layout.x.toString())
    rectangle.setAttribute('y', layout.y.toString())
    rectangle.setAttribute('width', layout.width.toString())
    rectangle.setAttribute('height', layout.height.toString())
  }
}// A custom visual creator implementation
// which renders a rectangle
class RectangleVisualCreator extends BaseClass<IVisualCreator>(IVisualCreator) implements IVisualCreator {
  // creates a new instance which renders the given rectangle
  constructor(public Rectangle: Rect) {
    super()
  }

  // Creates a visual
  createVisual(context: IRenderContext): Visual | null {
    const rect = window.document.createElementNS('http://www.w3.org/2000/svg', 'rect')
    rect.setAttribute('fill', '#6699CC')
    this.setLayout(rect, this.Rectangle)
    return new SvgVisual(rect)
  }

  // updates the layout
  updateVisual(context: IRenderContext, oldVisual: Visual): Visual | null {
    if (!(oldVisual instanceof SvgVisual)) {
      // If the visual is not of the expected type create a new one
      return this.createVisual(context)!
    }
    const rectangle = oldVisual.svgElement
    this.setLayout(rectangle, this.Rectangle)
    return oldVisual
  }

  private setLayout(rectangle: SVGElement, layout: Rect) {
    rectangle.setAttribute('x', layout.x.toString())
    rectangle.setAttribute('y', layout.y.toString())
    rectangle.setAttribute('width', layout.width.toString())
    rectangle.setAttribute('height', layout.height.toString())
  }
}

Developers who implement a IVisualCreator must keep in mind:

  • IVisualCreator instances must not store references to created visuals, as those may be cleaned up without the IVisualCreator knowing. Furthermore, createVisual may be called multiple times in different contexts. If updateVisual operates on stored Visual references, those stored references may not refer to the Visual instance passed to updateVisual.
  • updateVisual might be called with a Visual which has been created by a different IVisualCreator. Although in most cases the Visual has been created by the same IVisualCreator, there are situations where this is not the case, e.g. after the style of a graph item has been changed. Implementations have to be aware of this, note the type check in the updateVisual method in the example A custom IVisualCreator implementation.
  • An IVisualCreator may live longer than any of its created Visuals.
  • An IVisualCreator may create more than just one Visual.

The Scene GraphVisualizing Arbitrary Objects