C

RenderTree

Show Usages
Manages the tree of IRenderTreeElements and IRenderTreeGroups that render elements inside a CanvasComponent
Inheritance Hierarchy

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

Members

No filters for this type

Properties

backgroundGroup

: IRenderTreeGroup
readonly
Gets the IRenderTreeGroup that holds the rendering of the background elements.
The background group is the IRenderTreeGroup that should be used by the application code to put background elements in.
readonlyfinal

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.

See Also

Developer's Guide
API
foregroundGroup, contentGroup

contentGroup

: IRenderTreeGroup
readonly
Gets the IRenderTreeGroup that should be used by the application code to put actual content in.
The graph is usually visualized in this group.
readonlyfinal

See Also

Developer's Guide
API
backgroundGroup, foregroundGroup

focusGroup

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

See Also

Developer's Guide
API
highlightGroup, selectionGroup

foregroundGroup

: IRenderTreeGroup
readonly
Gets the IRenderTreeGroup that holds the rendering of the foreground elements.
The foreground group is the IRenderTreeGroup that should be used by the application code to put foreground elements in.
readonlyfinal

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(),
)

See Also

Developer's Guide
API
backgroundGroup, contentGroup

highlightGroup

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

See Also

Developer's Guide
API
focusGroup, selectionGroup

inputModeGroup

: IRenderTreeGroup
readonly
Gets the IRenderTreeGroup where the IInputModes should add their temporary content to.
This group by default is in front of the contentGroup.
readonlyfinal

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.

See Also

Developer's Guide
API
contentGroup, backgroundGroup, foregroundGroup

renderOrderComparator

: function(IRenderTreeElement, IRenderTreeElement): number
readonly
Gets an comparison instance that compares two IRenderTreeElement with respect to their rendering order.
An item is considered to be greater than another item if it is rendered on top of it.
readonlyfinal

Throws

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

rootGroup

: IRenderTreeGroup
readonly
Gets the root of the scene graph.
This group cannot be removed or reparented.
readonlyfinal

See Also

Developer's Guide

selectionGroup

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

See Also

Developer's Guide
API
focusGroup, highlightGroup

Methods

createElement

(parent: IRenderTreeGroup, visual: Visual): IRenderTreeElement
Adds a Visual to the scene graph as a child of the parent group.
final

Parameters

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

Return Value

IRenderTreeElement

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,
)

See Also

Developer's Guide
API
remove, IObjectRenderer

createElement

(parent: IRenderTreeGroup, visualCreator: IVisualCreator): IRenderTreeElement
Adds an IVisualCreator to the scene graph as a child of the parent group.
final

Parameters

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

Return Value

IRenderTreeElement

Examples

Providing an IVisualCreator instance
const renderTreeElement = graphComponent.renderTree.createElement(
  graphComponent.renderTree.backgroundGroup,
  new RectangleVisualCreator(rectangle),
)

See Also

Developer's Guide
API
remove, IObjectRenderer

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.
final

Parameters

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

Return Value

IRenderTreeElement

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,
)

See Also

Developer's Guide
API
remove, IObjectRenderer

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.
The renderer will be queried for the various rendering-related implementations for the given renderTag at rendering time.
final

Parameters

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.

Return Value

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,
)

See Also

Developer's Guide
API
remove, IObjectRenderer

createGroup

(parent: IRenderTreeGroup): IRenderTreeGroup
Adds a new IRenderTreeGroup to this group in the current scene graph.
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.
final

Parameters

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

Return Value

IRenderTreeGroup

See Also

Developer's Guide
API
remove

getBounds

(renderTreeElement: IRenderTreeElement): Rect
Calculates the bounds for a given render tree element.
This method queries the renderer for the IBoundsProvider for the tag and returns the result.
final

Parameters

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

Return Value

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.
This only iterates the leaves of the tree and will omit all inner nodes.
final

Parameters

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.

Return Value

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.
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.
final

Parameters

renderTreeElement: IRenderTreeElement
The render tree element.

Return Value

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.
final

Parameters

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

Return Value

IVisualCreator
an instance of the visual creator interface

See Also

API
getVisualCreator, VOID_VISUAL_CREATOR

hitElementsAt

(
location: Point
context?: IInputModeContext
root?: IRenderTreeGroup
): IEnumerable<IRenderTreeElement>
Returns an IEnumerable<T> of all hit elements in the canvas below the given group.
Hit testing is performed using the getHitTestable instance returned for each visible IRenderTreeElement in the current scene graph. The enumeration is performed lazily.
final

Parameters

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.

Return Value

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

See Also

Developer's Guide
API
IHitTestable, hitTestRadius, hitTestRadius

isHit

(renderTreeElement: IRenderTreeElement, location: Point): boolean
Tests if a given render tree element is hit at the given location.
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.
final

Parameters

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

Return Value

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.
final

Parameters

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

See Also

Developer's Guide

setParent

(element: IRenderTreeElement, newParent: IRenderTreeGroup)
Changes the parent of the given element to be the newParent.
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.
final

Parameters

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

See Also

API
remove