RenderTree

Manages the tree of IRenderTreeElements and IRenderTreeGroups that render elements inside a CanvasComponent

Inheritance Hierarchy

RenderTree

Remarks

This class keeps all relevant state and provides access to helper methods around the management of the render tree.

You don't create an instance of this type, but get it from the associated CanvasComponent's renderTree property.

It provides references to the predefined groups that are used for rendering various important parts of a CanvasComponent:

foregroundGroup – Elements that are rendered in the foreground of the visualization and in front of the actual contents.
inputModeGroup – Elements that are rendered typically in front of everything else and that typically only exist temporarily during user interaction like handles, marquee selection boxes, etc.
highlightGroup – A layer of elements that add a highlighting effect at the top of the visualization, but behind the interaction decorators.
focusGroup – A layer for showing the highlight to the user where the keyboard focus is.
selectionGroup – Layer showing the selection decoration for the contents.
contentGroup – The actual "contents" being displayed to the user, without any selection or input decoration, and excluding background rendering.
backgroundGroup – Elements that are rendered in the background of the visualization and behind the actual contents. The user typically does not interact with this group directly.

This class cannot be instantiated

Type Details

yFiles module: view

Properties

backgroundGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup that holds the rendering of the background elements.

Remarks

The background group is the IRenderTreeGroup that should be used by the application code to put background elements in.

Examples

The backgroundGroup can be used for displaying visuals in the background of the main content. For example, a background image:

Adding a background image to a CanvasControl

/**
 * Creates the image for the background visual.
 */
class ImageVisualCreator
  extends BaseClass<IVisualCreator>(IVisualCreator)
  implements IVisualCreator
{
  createVisual(context: IRenderContext): Visual {
    const image = window.document.createElementNS(
      'http://www.w3.org/2000/svg',
      'image',
    )
    image.setAttribute('width', '640')
    image.setAttribute('height', '480')
    image.setAttribute('x', '-150')
    image.setAttribute('y', '-160')
    image.setAttributeNS(
      'http://www.w3.org/1999/xlink',
      'href',
      'ylogo.svg',
    )
    return new SvgVisual(image)
  }

  updateVisual(context: IRenderContext, oldVisual: Visual): Visual {
    return oldVisual
  }
}

const renderTree = graphComponent.renderTree
renderTree.createElement(
  renderTree.backgroundGroup,
  new ImageVisualCreator(),
)

This image will scroll and zoom with the content, though. If a static image that doesn't move with the content is needed, add it as CSS background to the element of this component.

contentGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup that should be used by the application code to put actual content in.

Remarks

The graph is usually visualized in this group.

focusGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup which is used for visual markers of the currentItem.

foregroundGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup that holds the rendering of the foreground elements.

Remarks

The foreground group is the IRenderTreeGroup that should be used by the application code to put foreground elements in.

Examples

The foregroundGroup can be used for displaying visuals in the foreground of the main content. For example, a foreground image:

Adding an image to the CanvasControl foreground

/**
 * Creates the image for the foreground visual.
 */
class ImageVisualCreator
  extends BaseClass<IVisualCreator>(IVisualCreator)
  implements IVisualCreator
{
  createVisual(context: IRenderContext): Visual {
    const image = window.document.createElementNS(
      'http://www.w3.org/2000/svg',
      'image',
    )
    image.setAttribute('width', '640')
    image.setAttribute('height', '480')
    image.setAttribute('x', '-150')
    image.setAttribute('y', '-160')
    image.setAttributeNS(
      'http://www.w3.org/1999/xlink',
      'href',
      'ylogo.svg',
    )
    return new SvgVisual(image)
  }

  updateVisual(context: IRenderContext, oldVisual: Visual): Visual {
    return oldVisual
  }
}

const renderTree = graphComponent.renderTree
renderTree.createElement(
  renderTree.foregroundGroup,
  new ImageVisualCreator(),
)

highlightGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup which is used for visual markers to highlight IModelItems.

inputModeGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup where the IInputModes should add their temporary content to.

Remarks

This group by default is in front of the contentGroup.

Examples

In this example a custom IReshapeHandler installs a ghost visualization in the inputModeGroup.

initializeReshape(context: IInputModeContext) {
  this.originalHandler.initializeReshape(context)

  // ...

  const node = new SimpleNode({
    layout: this.originalHandler.bounds,
    style: new ShapeNodeStyle({
      fill: 'transparent',
      stroke: '2px solid gray',
    }),
  })

  const renderTree = context.canvasComponent!.renderTree
  this.shadowElement = renderTree
    .createElement(
      renderTree.inputModeGroup,
      node,
      GraphModelManager.DEFAULT_NODE_RENDERER,
    )
    .toFront()
}

cancelReshape(context: IInputModeContext, originalBounds: Rect) {
  context.canvasComponent.renderTree.remove(this.shadowElement)
  this.originalHandler.cancelReshape(context, originalBounds)
}

The sample shows only the initializeReshape method where the ghost is installed and cancelReshape where the ghost is removed, again.

renderOrderComparator

: function(IRenderTreeElement, IRenderTreeElement):number

Gets an comparison instance that compares two IRenderTreeElement with respect to their rendering order.

Remarks

An item is considered to be greater than another item if it is rendered on top of it.

Signature Details

function(x: IRenderTreeElement, y: IRenderTreeElement) : number

Encapsulates a method that compares two objects.

Parameters

x - IRenderTreeElement: The first object to compare.
y - IRenderTreeElement: The second object to compare.

Returns

number: An integer value which is <0 if x is less than y, 0 if x is equal to y, or >0 if x is greater than y

Throws

Exception({ name: 'ArgumentError' }): If one of the elements is not part of this tree.

rootGroup

: IRenderTreeGroup

Gets the root of the scene graph.

Remarks

This group cannot be removed or reparented.

selectionGroup

: IRenderTreeGroup

Gets the IRenderTreeGroup that should be used by the application code to put the selection indicators in.

Methods

createElement

<TRenderTag>(parent: IRenderTreeGroup, renderTag: TRenderTag, renderer: IObjectRenderer<TRenderTag>) : IRenderTreeElement

Adds a child element to the scene graph as a child of the parent group.

Remarks

The renderer will be queried for the various rendering-related implementations for the given renderTag at rendering time.

Type Parameters

TRenderTag

Parameters

options - Object
A map of options to pass to the method.

parent - IRenderTreeGroup: The parent group to which the child element is added.
renderTag - TRenderTag: The render tag to associate with this child element. This object will be passed to the renderer's methods.
renderer - IObjectRenderer<TRenderTag>: An implementation of the IObjectRenderer<T> interface that will be passed the renderTag to provide the various implementations that are used during rendering.

Returns

↪IRenderTreeElement: The IRenderTreeElement.

Examples

Providing an IVisualCreator instance as renderTag

const renderTreeElement = graphComponent.renderTree.createElement(
  graphComponent.renderTree.backgroundGroup,
  new RectangleVisualCreator(rectangle),
)

Using a renderTag which implements ILookup and returns its own IVisualCreator.

// the node provides an IVisualCreator via its lookup
const renderTreeElement = graphComponent.renderTree.createElement(
  graphComponent.renderTree.backgroundGroup,
  node,
)

Visuals provided as renderTag can be used "as is"

const image = window.document.createElementNS(
  'http://www.w3.org/2000/svg',
  'image',
)
image.setAttributeNS(
  'http://www.w3.org/1999/xlink',
  'href',
  'resources/background.png',
)
image.x.baseVal.value = 1
image.y.baseVal.value = 1
image.width.baseVal.value = 100
image.height.baseVal.value = 100
const visual = new SvgVisual(image)
graphComponent.renderTree.createElement(
  graphComponent.renderTree.rootGroup,
  visual,
)

createElement

(parent: IRenderTreeGroup, visual: Visual) : IRenderTreeElement

Adds a Visual to the scene graph as a child of the parent group.

Parameters

options - Object
A map of options to pass to the method.

parent - IRenderTreeGroup: The parent group to which the visual element is added.
visual - Visual: The Visual to add to the render tree.

Returns

↪IRenderTreeElement: The render tree element.

Examples

Providing a Visual

const image = window.document.createElementNS(
  'http://www.w3.org/2000/svg',
  'image',
)
image.setAttributeNS(
  'http://www.w3.org/1999/xlink',
  'href',
  'resources/background.png',
)
image.x.baseVal.value = 1
image.y.baseVal.value = 1
image.width.baseVal.value = 100
image.height.baseVal.value = 100
const visual = new SvgVisual(image)
graphComponent.renderTree.createElement(
  graphComponent.renderTree.rootGroup,
  visual,
)

createElement

(parent: IRenderTreeGroup, visualCreator: IVisualCreator) : IRenderTreeElement

Adds an IVisualCreator to the scene graph as a child of the parent group.

Parameters

options - Object
A map of options to pass to the method.

parent - IRenderTreeGroup: The parent group to which the visual creator is added.
visualCreator - IVisualCreator: The IVisualCreator to add to the render tree.

Returns

↪IRenderTreeElement: The render tree element.

Examples

Providing an IVisualCreator instance

const renderTreeElement = graphComponent.renderTree.createElement(
  graphComponent.renderTree.backgroundGroup,
  new RectangleVisualCreator(rectangle),
)

createElement

(parent: IRenderTreeGroup, lookup: ILookup) : IRenderTreeElement

Adds an ILookup implementation to the scene graph that provides the IObjectRenderer<T> interfaces (IVisualCreator, IBoundsProvider, IVisibilityTestable, IHitTestable) in its lookup implementation.

Parameters

options - Object
A map of options to pass to the method.

parent - IRenderTreeGroup: The parent group to which the element is added.
lookup - ILookup: The ILookup implementation to add to the render-tree.

Returns

↪IRenderTreeElement: The render-tree element.

Examples

Providing an object which implements ILookup and returns its own IVisualCreator.

// the node provides an IVisualCreator via its lookup
const renderTreeElement = graphComponent.renderTree.createElement(
  graphComponent.renderTree.backgroundGroup,
  node,
)

createGroup

(parent: IRenderTreeGroup) : IRenderTreeGroup

Adds a new IRenderTreeGroup to this group in the current scene graph.

Remarks

This can be used to build groups of IRenderTreeElement instances that can be moved within the scene graph or whose visibility can be controlled easily. The group will have a null tag.

Parameters

options - Object
A map of options to pass to the method.

parent - IRenderTreeGroup: The IRenderTreeGroup to add a new IRenderTreeGroup to.

Returns

↪IRenderTreeGroup: The render-tree element.

getBounds

(renderTreeElement: IRenderTreeElement) : Rect

Calculates the bounds for a given render tree element.

Remarks

This method queries the renderer for the IBoundsProvider for the tag and returns the result.

Parameters

options - Object
A map of options to pass to the method.

renderTreeElement - IRenderTreeElement: The render tree element to query the bounds from

Returns

↪Rect: The non-null bounds

getElements

(root?: IRenderTreeGroup, reverse?: boolean) : IEnumerable<IRenderTreeElement>

Enumerates over all possible IRenderTreeElement instances in the tree below the given group.

Remarks

This only iterates the leaves of the tree and will omit all inner nodes.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

root - IRenderTreeGroup: The group at which the enumeration should yield all the children recursively. If omitted/null, this will iterate over all elements in the tree.
reverse - boolean: Whether the elements should be iterated in reverse order. Elements rendered last (on top) will be enumerated first when set to true. This is useful for hit testing. When not specified, the default will be false which causes enumeration in declaration order.

Returns

↪IEnumerable<IRenderTreeElement>: A live enumerable for all IRenderTreeElements in the tree below the given group.

getVisual

(renderTreeElement: IRenderTreeElement) : Visual

Gets the Visual that is currently visualizing the given IRenderTreeElement.

Remarks

Note that depending on the current state of the viewport and the control no such instance may be available and instead this method will yield null. However, if a visual is currently being displayed for the given render tree element, it will be returned. This method should be used with care. Manipulation of the given instance should normally be done through the corresponding IVisualCreator that created the visual in the first place. This method rather serves as a utility method for UI testing frameworks and similar use cases.

Parameters

options - Object
A map of options to pass to the method.

renderTreeElement - IRenderTreeElement: The render tree element.

Returns

↪Visual?: The Visual that is currently used by the renderTreeElement. This may be null if the given renderTreeElement is currently not visible.

getVisualCreator

(renderTreeElement: IRenderTreeElement) : IVisualCreator

Retrieves the IVisualCreator for a given IRenderTreeElement.

Parameters

options - Object
A map of options to pass to the method.

renderTreeElement - IRenderTreeElement: the render tree element to query the visual creator implementation from

Returns

↪IVisualCreator: an instance of the visual creator interface

hitElementsAt

(location: Point, context?: IInputModeContext, root?: IRenderTreeGroup) : IEnumerable<IRenderTreeElement>

Returns an IEnumerable<T> of all hit elements in the canvas below the given group.

Remarks

Hit testing is performed using the getHitTestable instance returned for each visible IRenderTreeElement in the current scene graph. The enumeration is performed lazily.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

location - Point: the coordinates for the hit test.
context - IInputModeContext: The context to use for passing to the isHit implementations. If not specified, the CanvasComponent's inputModeContext will be used.
root - IRenderTreeGroup: the root of the scene graph or rootGroup if none is specified.

Returns

↪IEnumerable<IRenderTreeElement>: a live enumeration of the elements that are hit

isHit

(renderTreeElement: IRenderTreeElement, location: Point) : boolean

Tests if a given render tree element is hit at the given location.

Remarks

This method queries the renderer for the IHitTestable for the tag and returns the result of the hit test query. If there is no IHitTestable returned by the renderer, this method returns false.

Parameters

options - Object
A map of options to pass to the method.

renderTreeElement - IRenderTreeElement: the render tree element to test
location - Point: the coordinates of the query in the world coordinate system

Returns

↪boolean: whether the render tree element is hit at the given location

remove

(element: IRenderTreeElement)

Removes an element from this tree along with all its descendants if it's a group.

Parameters

options - Object
A map of options to pass to the method.

element - IRenderTreeElement: The element to remove from this render tree.

setParent

(element: IRenderTreeElement, newParent: IRenderTreeGroup)

Changes the parent of the given element to be the newParent.

Remarks

newParent also needs to be managed by and included in this render tree. element may not be the new parent or an ancestor of the new parent, either, as this would create a cycle.

Parameters

options - Object
A map of options to pass to the method.

element - IRenderTreeElement: The element to move to another parent.
newParent - IRenderTreeGroup: The new parent group element for element.

RenderTree

Remarks

Type Details

Properties

backgroundGroup

Remarks

Examples

See Also

contentGroup

Remarks

See Also

focusGroup

See Also

foregroundGroup

Remarks

Examples

See Also

highlightGroup

See Also

inputModeGroup

Remarks

Examples

See Also

renderOrderComparator

Remarks

Signature Details

Parameters

Returns

Throws

rootGroup

Remarks

selectionGroup

See Also

Methods

createElement

Remarks

Type Parameters

Parameters

Returns

Examples

See Also

createElement

Parameters

Returns

Examples

See Also

createElement

Parameters

Returns

Examples

See Also

createElement

Parameters

Returns

Examples

See Also

createGroup

Remarks

Parameters

Returns

See Also

getBounds

Remarks

Parameters

Returns

getElements

Remarks

ParametersOptions Overload

Returns

getVisual

Remarks

Parameters

Returns

getVisualCreator

Parameters

Returns

See Also

hitElementsAt

Remarks

ParametersOptions Overload