Migrating to 3.0 from 2.6

This article provides an overview of the most significant changes in version 3.0. For a complete list of changes, refer to the official changelog. For migration, we highly recommend using the yFiles Migration Tool.

Render objects

Renamings

Incompatible changes

• The new renderTree property on the CanvasComponent now encapsulates all low-level render object related API. Previously, these APIs were directly available on the CanvasComponent. This affects the following members on CanvasComponent:
  • Property backgroundGroup
  • Property contentGroup
  • Property focusGroup
  • Property highlightGroup
  • Property inputModeGroup
  • Property rootGroup
  • Property selectionGroup
  • Property renderOrderComparator
  • Method getElements

New API

• The new foregroundGroup on the RenderTree handles the rendering of foreground elements.
• The new createElement methods on RenderTree add elements to the CanvasComponent for rendering.

Removed API

• The ICanvasObjectInstaller has been removed in favor of the simpler IObjectRenderer<TRenderTag>.
• Removed the changed events for the render groups.
• Removed previously protected creation methods for the render groups.
• Removed constant ICanvasObjectDescriptor instances on ICanvasObjectDescriptor in favor of new RenderTreecreateElement methods
  • Constant ICanvasObjectDescriptor.ALWAYS_DIRTY_INSTANCE
  • Constant ICanvasObjectDescriptor.ALWAYS_DIRTY_LOOKUP
  • Constant ICanvasObjectDescriptor.ALWAYS_DIRTY_VISUAL
  • Constant ICanvasObjectDescriptor.DYNAMIC_DIRTY_INSTANCE
  • Constant ICanvasObjectDescriptor.DYNAMIC_DIRTY_LOOKUP
  • Constant ICanvasObjectDescriptor.VISUAL
  • Constant ICanvasObjectDescriptor.VOID
• Removed class VoidVisualCreator from the public API. An instance can be obtained from VOID_VISUAL_CREATOR.
• The more versatile IObjectRenderer<TRenderTag> replaces the previous IVisualTemplate such that VisualTemplate was removed from the API. Related resource keys are removed, and usages should be replaced with a renderer property on the related type.

Events and Event Registration

This migration can be performed automatically using the migration tool.

The event registration system for event listeners has been updated to align with the DOM model, transitioning to a standardized approach.

New Event Registration Methods

Method Parameters

eventName

String specifying the event type

callback

Function to be called when the event triggers

options

Optional object with configuration settingsThe options object can have the following properties: * once - When true, the listener is automatically removed after the first time it is triggered. * signal - An AbortControllersignal that can be used to manage the listener’s lifecycle.

Benefits

• Simplification: A single method handles all events.
• Flexibility: Supports single-use listeners.
• Control: Offers enhanced listener management through the AbortController.

Migration Example

graph.addNodeCreatedListener(callback)

graph.addEventListener('node-created', callback)

Migration Steps

1. Replace specific listener methods with addEventListener.
2. Convert event names to lowercase and use dashes as separators.
3. Add an options object when needed.

Callback Signature Changes

graph.addNodeCreatedListener((sender, eventArgs) => {
    // handle node creation
})

graph.addEventListener('node-created', (eventArgs) => {
    // handle node creation
})

Important Notes

• The sender argument has been moved to after the event argument in callbacks.
• Event handling now focuses directly on event arguments, which can conveniently be destructured, and the sender can be omitted. Typically, the sender is in the closure of the method definition anyway.
• This follows standard DOM event model conventions.
• An automatic migration is available via the migration tool.
• You can find more information about events in the Events section.

Replacing MouseEventArgs, TouchEventArgs with PointerEventArgs

Most of the below migration work can be performed automatically with the help of the migration tool.

yFiles for HTML 3.0 introduces a unified input event handling system using PointerEventArgs. This replaces the separate MouseEventArgs and TouchEventArgs classes, providing a more streamlined and efficient way to manage user input. This change simplifies code, reduces the number of types you need to handle, and provides a consistent API for mouse, touch, and stylus interactions.

The primary benefit is a unified API. Previously, you had to maintain separate logic for mouse and touch events. Now, you can use the pointerType and eventType properties of the PointerEventArgs to handle different input methods within a single event handler or event recognizer predicate.

Key Changes

The most significant change is the consolidation of MouseEventArgs and TouchEventArgs into a single PointerEventArgs class. This new class handles mouse, touch, and stylus inputs, simplifying event handling and reducing code duplication. PointerEventArgs provides properties to identify the source of the event (mouse, touch, or stylus) and access the specific input data for each.

New Features in PointerEventArgs

Pointer Type Identification

The PointerEventArgs class provides the pointerType property, which allows you to identify the type of device that triggered the event. The pointerType property is of type PointerType enum, which has the following possible values:

• MOUSE: Mouse device
• NONE: No device type
• PEN: Pen device
• TOUCH: Touch device

You can use this property to tailor your event handling logic based on the input device. For example:

graphComponent.addEventListener('pointer-move', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.MOUSE) {
    // Handle mouse-specific logic
    console.log('Mouse move event')
  } else if (evt.pointerType === PointerType.TOUCH) {
    // Handle touch-specific logic
    console.log('Touch move event')
  } else if (evt.pointerType === PointerType.PEN) {
    // Handle pen-specific logic
    console.log('Pen move event')
  }
})

The eventType property (of type PointerEventArgs) provides even more specific information about the event:

• ENTER: The pointer has entered the component’s bounds.
• MOVE: The pointer has been moved.
• DOWN: A pointer becomes active.
• DRAG: The pointer has been dragged, which means it has been moved while at least one button has been pressed.
• UP: A pointer button/state is no longer down.
• CLICK: A pointer click or touch/stylus tap has been recognized.
• WHEEL: The mouse wheel has been turned.
• LEAVE: The pointer has exited the component’s bounds.
• CANCEL: Pointer input has been canceled and cannot be relied upon anymore.
• DRAG_CAPTURE_LOST: Input capture has been lost while the pointer was dragging.
• LONG_PRESS: A long press has been recognized.
• LONG_REST: A long rest has been recognized.
• NONE: Not a pointer event.

Direct Property Access

PointerEventArgs provides direct access to properties specific to different input types. This includes:

• pointerSize: A Size object representing the width and height of the pointer’s contact area (for touch events).
• pressure: A number between 0 and 1 representing the normalized pressure of the pointer input (for stylus events).
• pointerId: A unique identifier assigned to the pointer causing the event, replacing the TouchDevice object from the old TouchEventArgs.
• isPrimary: Indicates if the pointer represents the primary pointer of this type.

Enhanced Gesture Handling

The PointerEventArgs simplifies gesture handling by providing a unified event stream for all input types. You can use the pointerType and eventType properties to create flexible gesture recognizers that work with mouse, touch, and stylus input.

Implementation Guide

Mapping Old Classes to New

The following table shows how to map properties from the old MouseEventArgs and TouchEventArgs classes to the new PointerEventArgs class:

PointerButtons Enum Mapping

The PointerButtons enum now encompasses states for mouse, pen, and touch inputs. Here’s how the old values map to the new enum:

Example: Migrating a Mouse Move Handler

graphComponent.addMouseMoveListener((sender, evt: MouseEventArgs) => {
  const worldLocation = evt.location
  console.log(`Mouse moved to: ${worldLocation.x}, ${worldLocation.y}`)
})

graphComponent.addEventListener('pointer-move', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.MOUSE) {
    const location = evt.location
    console.log(`Mouse moved to: ${location.x}, ${location.y}`)
  }
})

Example: Migrating a Touch Tap Handler

graphComponent.addTouchTapListener((sender, evt: TouchEventArgs) => {
  const worldLocation = evt.location
  console.log(`Touch tapped at: ${worldLocation.x}, ${worldLocation.y}`)
})

graphComponent.addEventListener('pointer-click', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.TOUCH) {
    const worldLocation = evt.location
    console.log(`Touch tapped at: ${worldLocation.x}, ${worldLocation.y}`)
  }
})

Using New Properties

Pressure-Sensitive Drawing

You could use the pressure property to change thickness or opacity of the created element based on the pressure applied by a stylus:

graphComponent.addEventListener('pointer-drag', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.PEN) {
    const strokeThickness = evt.pressure * 5 // Scale pressure to a thickness value
    // ... use strokeThickness to draw the line ...
  }
})

Enhanced Touch Interactions

The pointerSize property can be used to create more realistic touch interactions. For example, you could adjust the size of an element based on the size of the touch contact area.

graphComponent.addEventListener('pointer-drag', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.TOUCH) {
    const touchWidth = evt.pointerSize.width
    const touchHeight = evt.pointerSize.height
    // ... adjust element size based on touchWidth and touchHeight ...
  }
})

Compatibility Considerations

• scrollAmount: The scrollAmount property from MouseEventArgs is no longer directly available. If needed, you can access the originalEvent (the native DOM event) to get this information.
• Event Registration: Event registration has changed to DOM-style event registration using lowercase-dashed names for the event type. See the event registration section and the example below:

graphComponent.addMouseDownListener((sender, mouseEventArgs) => {
    // handle mouse down
})

graphComponent.addEventListener('pointer-down', (evt: PointerEventArgs) => {
    // handle node creation
    if (evt.pointerType === PointerType.MOUSE) {

    }
})

• Event Listeners: Make sure that you replace all addMouseMoveListener, addMouseUpListener, addMouseDownListener, addTouchMoveListener, addTouchTapListener, etc., calls with their addEventListener equivalents. Adapt the event registration as shown above. The "type" parameter is the lowercase-dashed name of the event type. You can do this automatically using the migration tool.

User Interaction

The default user interactions have been updated. Depending on your application, you may want or need to migrate your existing behavior to the new release. We have carefully updated keyboard shortcuts and default gestures to align with the standards found in many popular drawing and design applications like PowerPoint and Photoshop. If you have not made many customizations, the changes will be incompatible, but likely beneficial. Reverting the behavior to match the old defaults is possible, but requires different steps depending on the type of change.

Reverting Default Gestures in GraphEditorInputMode

The most noticeable change in GraphEditorInputMode is how elements are moved interactively. In version 2.6, you had to explicitly enable the option that allowed users to move elements without selecting them first. This is now the default behavior and can be disabled or controlled using the movableUnselectedItems property.

To continue supporting edge creation, the way edge creations are initiated has changed. Users now hover over a node to display the port candidates. Then, they can start dragging a new edge from a candidate, even if the node is selected. You can revert to the old behavior by setting startOverCandidateOnly to false, disabling moveUnselectedItemsInputMode, and assigning a higher priority to moveSelectedItemsInputMode.

const geim = new GraphEditorInputMode({
  createEdgeInputMode: { priority: 110, startOverCandidateOnly: false,
    showPortCandidates: 'end' },
  moveSelectedItemsInputMode: { priority: 100 },
  moveUnselectedItemsInputMode: { enabled: false }
})

In version 2.6, it was not intuitive for users on touch devices to cancel an edge creation gesture that was started by accident. By default, moving back to the start node without creating enough bends now cancels edge creation instead of creating a self-loop. You can revert to the old behavior by setting minimumSelfLoopBendCount to 0. In version 3.0, this property is set to 2 by default.

Reverting Changes in Keyboard Shortcuts

Most keyboard shortcuts in yFiles for HTML are configured via the yfiles.resources object, as explained in Customizing String Resources.

With yFiles for HTML 3.0, a number of changes were implemented:

• Keyboard Shortcut Changes: There were significant changes in keyboard shortcuts, especially for navigation and group manipulation (CollapseGroupKey, EnterGroupKey, ExitGroupKey, ExpandGroupKey, ToggleExpansionStateKey). Ctrl was changed to Control where appropriate.
• Arrow Keys Constant Names: The simple direction keys (Up, Down, Left, Right) have been replaced with ArrowUp, ArrowDown, ArrowLeft, and ArrowRight.
• Hierarchy Navigation: New keys have been added for extending selection and moving focus through a hierarchical structure.
• UpdateContentRect Key Renamed: The key UpdateContentRect has been renamed to UpdateContentBounds.
• Stripe Insets Key Renamed: The keys SetStripeInsets.RedoName and SetStripeInsets.UndoName have been renamed to SetStripePadding.RedoName and SetStripePadding.UndoName.

Changed Shortcut Syntax and Names

The names of the shortcut modifiers have been adjusted. If you have customized them, replace Ctrl with Control.

Changed Shortcuts

To revert to the original shortcut, set the property to the "old value."

Example: Using a Different Keyboard shortcut

yfiles.resources["invariant"]["ExtendSelectionUpKey"] = "Control+ArrowUp"

Added Shortcuts

Delete the property from the settings to revert the change.

delete yfiles.resources["invariant"]["IncreaseZoomKey"]

Theming

The Theme class and ThemeVariant enum have been removed. You can now change the theming through CSS classes.

ThemeVariant.CLASSIC has been removed and has no CSS replacement.

Migration Example

graphComponent.theme = new Theme({ scale: 2 })

<div id="graphComponent" style="--yfiles-theme-scale: 2"></div>

graphComponent.style.setProperty('--yfiles-theme-scale', '2')

For more about theming, refer to the Themes section.

Migrating WebGL2 Styles

The renamings shown below can be done automatically with the help of the migration tool.

In this release, WebGL2 styles now implement the standard interfaces:

• INodeStyle
• IEdgeStyle
• ILabelStyle

This integration enables seamless usage with standard IGraph API methods and infrastructure.

The following features now work directly with WebGL styles and no longer require special handling:

• Building Graphs
• Defaults configuration
• Undo functionality
• Clipboard operations
• Serialization
• Folding support

These changes will simplify your codebase by eliminating the need for special handling of WebGL styles.

1. Remove any special handling for WebGL styles.
2. Use standard style interfaces when specifying styles during:
   • Node creation
   • Edge creation
   • Label creation
3. Apply WebGL style instances directly in or during:
   • Element creation
   • Factories
   • Defaults
4. Instead of obtaining the WebGL style from WebGLGraphModelManager, obtain the style directly from the .style property of the elements.

Treat WebGL styles just like any other style in your application. No special considerations are required.

Example: Specifying WebGL2 Style instances

const node = graph.createNode({
  style: new WebGLShapeNodeStyle({
    fill: '#242265',
    effect: 'ambient-stroke-color',
    stroke: '3px dashed orangered',
    shape: 'hexagon',
  })
})

graph.nodeDefaults.style = new WebGLImageNodeStyle(someImageData)

graphComponent.inputMode = new GraphEditorInputMode({
  createEdgeInputMode: {
    edgeDefaults: {
      style: new WebGLArcEdgeStyle(
        { stroke: "3px solid darkblue", height: 20, fixedHeight: true }
      )
    }
  }
})

Level of Detail Rendering with WebGL and Non-WebGL styles

For applications that dynamically switch between WebGL mode and SVG/HTML/Canvas rendering, the WebGL styles are automatically mapped to visually similar SVG-based styles. When using level of detail rendering and custom styles are desired in SVG mode, a convenience implementation is available. This implementation implements the corresponding style interface, allowing you to specify both the WebGL and the non-WebGL style instance.

Example: Specifying a WebGL2 Style and an SVG Style for Level of Detail Rendering

const node = graph.createNode({
  style:
    new WebGLNodeStyleDecorator(
      myCustomNodeStyle,
      new WebGLImageNodeStyle(someImageData)
    )
})

WebGL API Changes in yFiles for HTML 3.0

Most types that had a WebGL2 prefix now have the 2 removed from their name.

WebGL2Visual still has the WebGL2 prefix, as there already is a WebGLVisual, that is used for working with WebGL 1.

Clipboard API Changes

The renaming aspects of the migration below can be performed automatically using the migration tool.

GraphEditorInputMode Event Changes

The following events now use ItemsEventArgs and have their names adjusted. See Events and Event Registration for details on how events are handled in 3.0.

• elementsCut → items-cut
• elementsCopied → items-copied
• elementsPasted → items-pasted
• elementsDuplicated → items-duplicated
• deletedSelection → deleted-selection

Changes of IClipboardHelper

• Added methods to support duplicate:
  • shouldDuplicate: Determines whether duplication is supported.
  • onDuplicated: Handles the duplication of items.
• Renamed methods:
  • cut → onCut
  • copy → onCopied
  • paste → onPasted
• Changes to method signatures:
  • cut and copy no longer return an object. If you need to pass information between cut/copy and paste, store that information in your implementing class (on this).
  • Removed object parameter from paste and shouldPaste. Get the information from the instance (this).

GraphClipboard Changes

• Now uses the specialized ClipboardGraphCopier instead of the general GraphCopier
• Added the static member DEFAULT_GRAPH_CLIPBOARD, which is the clipboard shared by all GraphComponent instances if no other instance is specified.
• paste now accepts an optional pasteLocation parameter specifying the center of the bounds of the pasted items.
• Members of GraphClipboard with "Element" in their name that referred to model items were renamed to use "Item" instead.
• The following properties have been changed:
  • empty has been renamed to isEmpty
  • pasteDelta has been renamed to pasteOffset
  • isDummy has been renamed to isHelper
  • clipboardGraph is now read-only
• The following methods have been removed; use the property setters instead:
  • createClipboardGraph
  • createToClipboardCopier
  • createFromClipboardCopier
  • createDuplicateCopier
  • createDefaultClipboardIdProvider
  • getMemento
  • getClipboardHelper

Folding API Changes

These renaming aspects of the migration below can be performed automatically using the migration tool.

Core Changes

• Simplified configuration of edges at folder nodes.
• Allow propagation of property changes of elements in the folding state back to the master configurations.
• Enhanced default implementation for folder nodes and folding edge converters.
• Collapsed group nodes can now have different tags from their expanded form.

Interface Updates

IFolderNodeConverter

• Added a new updateGroupNodeState method to propagate changes from the folder node back to the corresponding group node.
• The DefaultFolderNodeConverter (renamed to FolderNodeConverter) now uses FolderNodeDefaults to manage state configuration. The FolderNodeDefaults API has a structure similar to the INodeDefaults interface. For each node aspect (ports, labels, port labels), you can configure whether changes are synchronized in either direction.

IFoldingEdgeConverter

• Added a new updateMasterEdges method to propagate changes from the folding edge back to the edges it represents.
• Both DefaultFoldingEdgeConverter (renamed to FoldingEdgeConverter) and MergingFoldingEdgeConverter now use FoldingEdgeDefaults to manage state configuration. The FoldingEdgeDefaults API has a structure similar to the IEdgeDefaults interface. For each edge aspect (ports, labels), you can configure whether changes are synchronized in either direction.

Behavioral Changes

• In folding view graphs, createGroupNode always creates a group, regardless of the isExpanded predicate.
• Changes to view states can be reflected back to master items using:
  • updateGroupNodeState for folder nodes
  • updateMasterEdges for folding edges

To respect the isExpanded predicate, create the group node in the master graph instead of the folding view graph.

GraphML changes

Core Changes

• Reflection metadata for types and properties has been completely reworked. Instead of using $meta annotations in a class declaration, you should now provide type metadata through external annotations. This also affects how markup extensions are registered. The attribute classes GraphMLAttribute and TypeAttribute have been removed as well.
• Other configuration and customization of GraphML I/O has been simplified. All configuration should now be done through the GraphMLIOHandler class.

API changes

Changes to class GraphMLIOHandler

The following classes, methods, and properties have been removed. Their functionality has been replaced by reasonable default values or moved to application logic:

• Properties writeSharedReferences and writeXMLSchema: These are now always enabled.
• Method addInputHandlerFactory and the interface IGenericInputHandlerFactory: This functionality should now be implemented as part of the application logic.
• Method addInputMapperFuture and the class Future: This functionality should now be implemented as part of the application logic.
• Methods addRegistryInputMapper and addRegistryOutputMapper: You need to manage the association between attribute names and IMapper<K,V> instances as part of the application logic.

The following classes, methods, and properties have been removed. Their functionality is now provided by the listed alternatives:

• Protected methods configureDeserializationHandlers, configureSerializationHandlers, configureInputHandlers, and configureOutputHandlers have been removed. All protected handle*Serialization, handle*Deserialization, register*InputHandler, and register*OutputHandler methods have been removed as well. Use the corresponding handle-deserialization, handle-serialization, query-input-handlers, and query-output-handlers events instead to configure additional input or output features or enable or disable predefined features.
• All other protected configure* methods have been removed. Use the new methods configureParseContext and configureWriteContext or the provided SerializationProperties instead.
• All protected on* methods that raised an event have been removed. Subscribe to the corresponding event instead.

Changes to support classes and interfaces

• Classes GraphMLParser and GraphMLWriter and their creation and configuration methods on GraphMLIOHandler have been removed. All I/O configuration should now happen through class GraphMLIOHandler.
• Enums GraphMLSharingPolicy and SharingState and the interfaces IReferenceHandle and IReferenceHandler have been removed. All reference handling is now performed by the framework.
• Interfaces IGraphElementIdAcceptor and IGraphElementIdProvider have been removed. Use GRAPH_ELEMENT_IDS and GRAPH_IDS instead.
• Class XmlWriter has been removed. Use the instance of IXmlWriter that is provided by the write context instead.
• Helper class GraphMLSupport and enum StorageLocation have been removed. This functionality should now be implemented as part of the application logic.

Changes to the file format

• The default XML namespaces have changed:
  • Most types that were in the http://www.yworks.com/xml/yfiles-common/3.0 XML namespace have been moved to the http://www.yworks.com/xml/yfiles-common/4.0 XML namespace. A few types that are needed for basic compatibility with other platforms remain in the old namespace.
  • All types that were in the http://www.yworks.com/xml/yfiles-for-html/2.0/xaml XML namespace have been moved to the http://www.yworks.com/xml/yfiles-for-html/3.0/xaml XML namespace
• Changes to the object representation:
  • Most changes to types and properties are reflected in the corresponding GraphML representation. A few types and properties that are needed for basic compatibility with other platforms retain their old GraphML representation.

The graphml-compatibility source code sample enables parsing of GraphML files written by yFiles for HTML 2.x:

import { configureGraphMLCompatibility } from 'graphml-compatibility/GraphMLCompatibility'
configureGraphMLCompatibility(graphMLIOHandler)