yFiles WPF 3.0 - Changes Since 2.5.0.4

Major Features Added

General

The complete yFiles WPF API has been overhauled, simplified, and made more consistent. Many strange and dark corners of the API have been cleaned up. Types have more logical and intuitive names. The namespace structure is more logical and intuitive as well.

The Developer's Guide has been completely revised. It now consists of two major parts: The first part covers the basics of yFiles WPF, while the second part describes in detail how the behavior of the library can be adapted to the customer's requirements.

API documentation and Developer's Guide are now integrated into our Documentation Viewer that provides useful search and filtering facilities.

Viewer

Running animations and performing layouts now offers .NET's Task-based mechanism for asynchronous processes. This leads to easier composition of asynchronous processes using C#'s await keyword where code is written close to how synchronous code would look like instead of chaining callbacks. This also simplifies exception handling which works as usual via try/catch instead of callbacks.

Layout

Performance for many layout algorithms has been improved.

There now is a new way to configure yFiles automatic layout algorithms. The LayoutData class and its sub-classes can be used to pass configuration data to a layout algorithm by setting properties instead of registering DataProviders on the graph which have to be filled with this data. This reduces the code needed to configure a layout and is more flexible as well as reusable. As most subclasses of LayoutData are specialized for one layout algorithm, their properties provide a good overview which data can be passed to the algorithm.

Added new layout algorithm SeriesParallelLayout for graphs that are constructed only by series (combining two series parallel graphs by merging the source of one graph with the sink of the other) and parallel (combining two series parallel graphs by merging the sources and the sinks) operations.

Added edge bundling feature. Bundling together multiple edges means that their common parts are to some degree merged into a bundled part. Edge bundling is useful to increase the readability of graph drawings with a high number of edges that connect a comparably small number of nodes. The following layout algorithms support edge bundling:

CircularLayout: Edge bundling is applied to edges of the same partition.

TreeReductionStage: Edge bundling is applied to non-tree edges.

RadialLayout: Edge bundling is applied to non-tree edges.

Added support for Sankey diagrams which visualize flow quantity between entities like e.g., cost or energy flow.

OrganicLayout now supports the detection of regular substructures in the graph (see OrganicLayout.ChainSubstructureStyle, OrganicLayout.StarSubstructureStyle, OrganicLayout.CycleSubstructureStyle, and OrganicLayout.ParallelSubstructureStyle) and applies a specific layout style to them such that they can be better recognized.

Deployment

The Software License Agreement now provides an alternative to the requirement of obfuscating the redistributable DLLs: delivering the redistributables as part of software applications is now allowed if the redistributable DLLs are obfuscated or if the assemblies of the application which reference yFiles are signed with a strong name whose public key token is bound to the license. See distribution.html for details.

Minor Features Added

Layout

Added multi-parent support to TreeLayout. A tree node can have multiple parents that are connected to all of its siblings and share the same parents. This might come to use in organizational charts where a team answers to multiple superiors.

Added grid placement support for nodes and edges to HierarchicLayout.

RecursiveGroupLayout: Added the InterEdgeRouter property to specify an edge router to layout edges that cross group node bounds. Thus, it is not necessary to subclass the layout algorithm to change inter-edge routing anymore.

HierarchicLayout supports recursively routed edges. Edges that pass the border of group nodes will always leave at the bottom side and enter at the top side of the group node. This routing style is specified using EdgeLayoutDescriptor.RecursiveEdgeStyle.

HierarchicLayout: Improved from-sketch behavior for groups with changed bounds (e.g. after folding or expanding a group node).

HierarchicLayout: Added support for port grouping, see PortConstraintKeys.SOURCE_PORT_GROUP_ID_DP_KEY and PortConstraintKeys.TARGET_PORT_GROUP_ID_DP_KEY. Edges are bundled at their ports, but routed independently.

HierarchicLayout now allows to specify the directedness of edges, see HierarchicLayout.EDGE_DIRECTEDNESS_DP_KEY. This new feature enables to, for example, support mixed graphs that contain both directed and undirected edges: While for directed edges the layering step tries to find a solution where the source of an edge is placed above the target (with respect to the main layout direction), for undirected edges the direction doesn't matter and the edge may also be inserted as same-layer edge. This feature also enables to force some edges to specifically point against the main layout direction.

HierarchicLayout: Added support for edges with a specific thickness. Minimum distances in the layout will consider these thicknesses, see HierarchicLayout.EDGE_THICKNESS_DP_KEY.

Incompatible Changes

General

The return type of several methods has been changed from IEnumerator<T> to IEnumerable<T>.

Many usages of ref or out parameters have been replaced with a suitable structure as return type. The most prominent example of this change are the various GetTangent methods in IPathGeometry and GeneralPath that now return a Tangent.

All methods that take a parameter of type ICanvasContext, IRenderContext, IInputModeContext, IParseContext, IWriteContext, SnapContext, GraphSnapContext, or LabelSnapContext now have that parameter as their first parameter.

With the new web-based Documentation Viewer, the integrated help for the Visual Studio Help Viewer has been discontinued.

Namespace Structure

Classes of the viewer part have been reorganized into a simpler namespace structure.

Model

IGraph

IGraph now supports grouping by default. The GroupingSupported property has been removed from DefaultGraph. Grouping is now always enabled for graphs.

The new property AllowGroupingOperations on GraphEditorInputMode allows for switching interactive grouping operations on or off. Grouping operations are disabled by default and have to be enabled explicitly if the input mode should support them.

The grouping support interfaces IGroupedGraph and IHierarchy<T> have been removed and folded with IGraph.

IHierarchy<T>'s Root property is no longer available. The root of a grouping hierarchy is now represented by null.

Overhaul of IGraph's CreateNode, CreateEdge, AddLabel, AddPort: Ambiguous overloads have been removed, missing overloads have been added and parametershave been ordered to be consistent throughout all overloads.

IGraph's Nodes, Edges, Labels, and Ports properties have been changed from ICollectionModel to IListEnumerable. To be notified of created or removed items, the corresponding IGraph events should be used instead.

The properties NodeLabels and EdgeLabels on IGraph have been replaced by the extension methods GetNodeLabels and GetEdgeLabels.

The properties CollectionModel and Bends have been removed. Bends has been replaced by the GetBends extension method.

The classes BendList and ListLabelCollection have been removed. Use ListEnumerable instead.

The signatures of event handlers throughout the IGraph API have been made consistent using properly typed EventArgs subtypes. Exceptions are a few events that are raised very often which retain an argument list to improve performance.

The methods IsLeaf/SetLeaf and related properties and events have been replaced by IsGroupNode/SetIsGroupNode which have the exact opposite meaning from the old ones.

The signature of IGraph.AddBend has changed. The index parameter has been moved to the end and made optional.

The IGraphStructure interface and its SimpleGraphStructure implementation have been removed, as well as DefaultGraph's constructor that accepted an IGraphStructure.

IGraph now extends the ITagOwner interface. Thus graphs now have a Tag property.

DefaultGraph

DefaultGraph now raises removal events for labels, ports, and bends which are implicitly removed when their owner is removed.

Various protected factory methods on DefaultGraph have been removed: CreateNodeDefaults, CreateEdgeDefaults and CreateMapperRegistry, amongst others.

The method GetBounds has been removed from DefaultGraph.

The property UsePortCandidateProviders has been removed from both DefaultGraph and GraphSettings. Creating an edge using port candidate providers has to be done by manually querying the provider and calling CreateEdge(IPort, IPort).

Folding

The method IsInitiallyExpanded has been removed from IFoldedGraph. The methods IsInitiallyExpanded, SetInitiallyExpanded, and the property DefaultExpandedPredicate have been removed from FoldingManager.

The Expand, Collapse, and IsExpanded methods on IFoldingView (previously IFoldedGraph) now also work with nodes that belong to the master graph instead of the view graph. Thus the collapsed/expanded state can be set or queried for items that are currently not in the view graph. This replaces part of the removed functionality mentioned above.

The interfaces IChangeDummyNodeAppearanceCallback, IChangeDummyEdgeAppearanceCallback, and IChangeLabeledItemAppearanceCallback as well as the FoldingManager.GetChangeDummyAppearanceCallback methods have been removed. The view state properties can now directly be changed on the view state implementations returned by FoldingManager.GetFolderNodeState and FoldingManager.GetFoldingEdgeState, respectively.

IFoldingView.IsInFoldingState (previously IFoldedGraph.IsDummy) now throws an ArgumentException for labels and ports that are not part of this view. Previously, this method returned true for such items. Since this exception is already thrown for nodes, edges, and bends that are not part of this view, the behavior is now the same for all types of graph items.

Labels

The order of the parameters of ILabelModel.GetGeometry has been changed to ILabelModel.GetGeometry(ILabel, ILabelModelParameter).

FreeNodeLabelModel.CreateNodeCenterAnchored and FreeNodeLabelModel.CreateNodeLayoutAnchored have been removed.

FreeNodeLabelModel.CreateDefaultParameter now uses the label's center as its anchor point.

The new edge label models EdgeSegmentLabelModel and EdgePathLabelModel have been added. EdgeSegmentLabelModel allows to create parameters for a segment index and segment ratio while EdgePathLabelModel creates parameters using a ratio of the edge path.

The new label models replace the following removed label models: RotatingEdgeLabelModel, SliderEdgeLabelModel, SideSliderEdgeLabelModel, RotatedSliderEdgeLabelModel, and RotatedSideSliderEdgeLabelModel.

The label layout parameter of the edge label defaults now uses the EdgeSegmentLabelModel.

Ports

The property IPort.Location (to obtain a snapshot of the port's location) has been replaced by the extension method GetLocation. To retrieve a live view of the location of a port, use the new extension method IPort.DynamicLocation.

NodeScaledPortLocationModel has been replaced by FreeNodePortLocationModel that allows to specify the port location by a ratio of the node layout's size and an additional offset. The placement options and API are very similar to FreeNodeLabelModel.

AnchoredPortLocationModel has been removed.

Table

ITable interface:

The signature of CreateRow and CreateColumn has changed. The index parameter has been moved to the end and made optional.

The events StripeChanged and StripeRemoved use StripeEventArgs now. The corresponding event raiser methods have been changed accordingly.

The event LabelRemoved uses LabelEventArgs now.

New extension methods have been added: FindColumn, FindRow, GetCellBounds.

Table class:

The table's lookup decorator can now decorate stripe labels, too.

The following methods have been removed: CreateDefaultColumnStyle, CreateDefaultColumnInsets, CreateDefaultColumnLabelStyle, CreatedDefaultColumnLabelModelParameter, CreateColumnLabelDefaults, CreateDefaultRowStyle, CreateDefaultRowInsets, CreateDefaultRowLabelStyle, CreatedDefaultRowLabelModelParameter, CreateRowLabelDefaults, RemoveUndoSupport, some overloads of CreateRow/CreateColumn, some overloads of AddLabel

The properties DefaultStripeLookup, DefaultColumnLookup and DefaultRowLookup have been added, which replace the removed classes with the same same.

TableExtensions: The GetElementsToMove method has been removed

The IStripeSelection.SelectedStripes property has been removed. Use the individual properties for SelectedRows and SelectedColumns instead

StripeSelection: The superfluous overloads of IsSelected and SetSelected taking an IRow or IColumn have been removed.

The static helper method PlaceNodeInCell has been added to ITable to easily move a node into a specific table cell.

Undo Support

Extension methods to enable/disable Undo have been added to IGraph.

Setting the Tag property on model items and the graph now works with Undo.

Undo operations for the removal of graph elements now keep the proper item order. This improves the consistency especially for layouts between undo operations.

Overloads of the IGraph.BeginEdit extension method that work with IMementoSupport (either via ILookup or an IMementoSupportProvider) have been added.

The overload of the IGraph.BeginEdit extension method that accepted an IEnumerable of IModelItems has been removed.

IUndoSupport, MementoUndoUnit, MementoUndoableEdit, and MementoStateStruct have been removed.

IUndoUnit: The methods CanUndo and CanRedo have been removed.

The methods UndoImpl and RedoImpl on UndoUnitBase have been removed. Implementations should use Undo and Redo from the IUndoUnit interface instead.

The properties UndoText and RedoText on UndoEngine have been removed.

The interface IGraphUndoUnitSupport has been removed. Its methods Create...UndoUnit have been moved to DefaultGraph. Developers who have created a custom implementation have to derive from DefaultGraph and override the corresponding method(s).

Geometry

The yWorks.Geometry namespace has been simplified and cleaned up.

The basic geometry types PointD, SizeD, RectD and InsetsD have been made immutable.

The classes ImmutablePoint, ImmutableSize, ImmutableRectangle and ImmutableOrientedRectangle have been removed. The immutable types PointD, SizeD and RectD as well as the immutable instance provided by the new static method OrientedRectangle.CreateImmutable can be used instead.

The interfaces IPointSetter and ISizeSetter have been removed. Instead the interfaces IMutablePoint and IMutableSize are used.

The IReshapeable interface has been removed. The various overloads of the Reshape method have been implemented as extension methods on IMutableRectangle instead.

IMovable has been removed as well. Instead an IPositionHandler can be used.

PointD.FromPoint, SizeD.FromSize and RectD.FromRectangle have been removed and replaced by the extension methods IPoint.ToPoint, ISize.ToSize, and IRectangle.ToRect.

Various other geometry-related infrequently-used or duplicate classes and interfaces have been removed.

The static fields SizeD.Unbound, SizeD.Empty and SizeD.Zero have been added.

Controls

The ContentRect will now also be updated when creating edges, adding, editing or moving labels or deleting graph items.

The Cut, Copy and Paste commands are no longer handled by GraphControl and the respective methods have been removed as well. Command bindings for Copy are still supplied by GraphViewerInputMode and GraphEditorInputMode. Command bindings for Cut and Paste are still supplied by GraphEditorInputMode.

The Undo and Redo commands are no longer handled by GraphControl and the respective methods have been removed as well. Command bindings for Undo and Redo are still supplied by GraphEditorInputMode. Furthermore, the respective methods can still be called on the UndoEngine directly.

The UndoabilityEnabled property has been removed. Undo and Redo command bindings can be enabled on GraphEditorInputMode.

The ClipboardEnabled property has been removed. Clipboard command bindings can be enabled on GraphViewerInputMode and GraphEditorInputMode.

The GetUndoEngine method has been removed. The current UndoEngine can be retrieved from the graph instead.

The SelectionChanged event has been removed.

The new property LastEventLocation always contains the location of the last mouse or touch event.

The MouseWheelBehavior property replaces the previous property AutoMouseWheelZoomEnabled and not only allows disabling mouse wheel zoom, but also enabling scrolling with the mouse wheel.

The methods Add, AddCreator, AddGroup and AddGroupToGroup have been removed as the new methods AddChild and AddGroup of ICanvasObjectGroup provide a more intuitive way to add child elements to e.g. the GraphControl.GetBackgroundGroup.

The InputModes property has been removed. Developers who want to install multiple input modes on a CanvasControl have to set a MultiplexingInputMode as CanvasControl.InputMode and add their input modes to that mode.

Removed superfluous interfaces IUserTagProvider and ITableProvider, and all implementations.

Removed superfluous constructors from all style implementations.

All IStyleRenderer implementations: The accessibility of the Style, Layout, and Item properties has been reduced to protected. In addition, the latter has been renamed to Node, Label, Edge, or Port respectively.

Animations

The original overloads of Animator.Animate that accept a callback for finishing the animation have been removed. Instead the new Task-based overloads can be used.

Various Visualization Changes

The protected factory methods that supplied the initial value for GraphModelManager's Installer properties (EdgeStyleInstaller, NodeStyleInstaller, etc.) have been removed.

GraphModelManager.Invalidate has been removed.

Added a mechanism to support deterministic disposal and caching Visuals which have been created by IVisualCreator.CreateVisual. Add methods SetDisposeCallback, ChildVisualRemoved, and RegisterForChildrenIfNecessary to IRenderContext.

The IRenderContext.Canvas method has been pulled up to ICanvasContext and renamed to CanvasControl.

IRenderContext: The Transform property has been removed.

The RenderContext class has been removed. Use CanvasControl.CreateRenderContext instead to retrieve an instance of IRenderContext.

DefaultEdgePathCropper now uses the new method HandleEmptyPath if cropping the edge would result in an empty path. By default this method crops at the ports instead which results in edges between a group node and one of its children being no longer hidden.

DefaultEdgeIntersectionCalculator: A callback method GetNodeGeometry has been added.

The CanvasObjectGroupProviderCallback property on ModelManager has been replaced with the GetCanvasObjectGroup method. The CanvasObjectGroupProviderCallback property on ItemModelManager has been replaced with the CanvasObjectGroup property and the GetCanvasObjectGroup method; the default implementation just defers to the property, just like GetDescriptor.

IGroupAction as well as ICanvasObjectGroup.GetGroupAction have been removed as they had hardly any use.

The interface ICanvasGroupProvider and the delegate CanvasObjectGroupProviderCallback have been removed. Accessing the individual CanvasObjectGroups can be done via the properties of CanvasControl instead.

ICanvasObjectTreeEventSource and the corresponding classes CanvasObjectAddEventArgs, CanvasObjectRemoveEventArgs, CanvasObjectMoveEventArgs, and CanvasObjectInvalidateEventArgs have been removed.

Input

General Input Mode Refactorings

The type hierarchy for input modes has been simplified considerably:

All input modes except OverviewInputMode, GraphViewerInputMode, and GraphEditorInputMode now directly implement IInputMode without any abstract base classes in between.

IConcurrentInputMode has been removed and merged with IInputMode.

The Enabled property on the IInputMode interface has been removed. It is still present on all concrete implementations.

The ConcurrencyController property has been removed. Instead, a parameter of type ConcurrencyController has been added to the IInputMode.Install method.

All abstract input mode base classes except AbstractInputMode (which has been renamed to InputModeBase) have been removed. AbstractConcurrentInputMode has been merged into InputModeBase.

Input mutex handling has been refactored considerably:

IInputMode's ConcurrencyController property has been removed. Input modes now get a ConcurrencyController as parameter of their Install method.

The ConcurrencyController has been refactored and is now only responsible for a single input mode. Its Active property indicates if the input mode currently has or may request the mutex.

The InputMutex class has been removed.

The PreferredCursor property has been moved from IInputMode to ConcurrencyController.

The input mutex should be requested and released using the according methods on ConcurrencyController. Most input modes don't provide the methods HasMutex, CanRequestMutex, RequestMutex and ReleaseMutex anymore.

The Enabled property of IInputModes is not set to false anymore if another input mode acquires the mutex. Instead their ConcurrencyController is deactivated. This provides a clear separation between suppressing input modes (while another mode holds the mutex) and explicitly disabling a mode from user code (via the Enabled property).

As a consequence most input modes don't provide the EnabledChanged event and the OnEnabled and OnDisabled methods anymore, but OnConcurrencyControllerActivated and OnConcurrencyControllerDeactivated instead.

IInputMode has a new property Priority which defines the installation priority of the input mode. Previously those have been available as properties on GraphViewerInputMode, GraphEditorInputMode, and TableEditorInputMode. Those have been removed.

IInputMode's Stop method has been renamed to TryStop to make it more obvious that an implementation might return false to indicate that it did not actually stop.

All input modes no longer raise Stopped and Canceled events. Developers who want to get notified when an input mode gets stopped or canceled have to override the OnStopped or OnCanceled methods. Also, the events Initializing and Initialized no longer exist. Input modes that need to perform one-time initialization on first Install can keep track of that themselves.

MultiplexingInputMode: The AddConcurrent methods as well as the Add method which takes an additional priority parameter have been removed. There is only one Add method left, which takes an input mode as its only parameter. Priority is determined by the input mode's Priority property. Whether an input mode runs exclusive or always active alongside other input modes is determined by the input mode's ConcurrencyController which has an Exclusive property controlling that. This property is also available for all default IInputMode implementations.

MultiplexingInputMode is now aware of changes to the priority of already installed input modes and will update the installation order accordingly when an input mode's priority is changed.

IInputModes in general:

The setter for Graph and GraphSelection properties, if present, and its associated Set* methods have been removed. Both are now always retrieved from the input mode context dynamically.

The read-only property InputModeContext has been introduced to expose the IInputModeContext the mode is installed in.

Many input modes now no longer have protected methods for state machine transitions. Instead those methods are mostly parameterless now.

GraphEditorInputMode and GraphViewerInputMode

GraphViewerInputMode and GraphEditorInputMode have been made more similar regarding customization in the capabilities they both provide:

GraphViewerInputMode now supports the same click and selection behavior as GraphEditorInputMode. This includes detail selection (Shift+Click) and cyclic selection (Alt+Click) as well as finer control over behavior like the ClickSelectableItems property and the ShouldClickSelect method.

The methods Click and DoubleClick now take an IModelItem and ClickEventArgs as arguments and have no return value. Instead of returning a boolean, the Handled property on the ClickEventArgs should be set.

Their ClickInputMode instances is now configured to raise events for both left and right clicks.

The default click actions that change the selection and create new nodes are only triggered on left mouse clicks now.

An explicit hit-test order for double clicks is provided that can be changed through the DoubleClickHitTestOrder property. By default, this hit-test order prefers labels over other graph elements.

GraphViewerInputMode now also has the AvailableCommands property, already known from GraphEditorInputMode or NavigationInputMode.

Several child input mode priorities in GraphViewerInputMode have been changed and most of them now have the same priorities as in GraphEditorInputMode.

The new CanvasClicked event reports clicks on an empty canvas location.

The new SelectablePredicate property allows finer control over what particular items should be selectable without the need to create a custom subclass.

The new CreateSelectionEventArgs method creates SelectionEventArgs using the GraphSelection.

The events MultiSelectionStarted and MultiSelectionFinished now use SelectionEventArgs<IModelItem>.

GraphViewerInputMode now has improved support for marquee selection. Marquee selection is no longer turned on or off via MarqueeSelectableItems but instead directly on the MarqueeSelectionInputMode. The recognizer for marquee selection is Shift+Drag and the child input mode priorities have been adjusted accordingly so that marquee selection and viewport movement can co-exist. The child input mode still defaults to being disabled, though.

Changing the ShowHandleItems property will now immediately update the currently visible handles.

The new DeletablePredicate property allows finer control over what particular items should be deletable without the need to create a custom subclass.

The new LabelAdding and LabelEditing events have been added. Those allow fine-grained control over adding or editing labels and tie into the existing functionality provided by IEditLabelHelper.

TextEditorInputMode now ensures that the TextBox is visible in the viewport when starting editing. This behavior can be adjusted by creating a custom subclass and overriding the EnsureVisible method.

Cleanup of the old GraphEditorInputMode API

The type of the OrthogonalBendRemoval property has been changed from bool to OrthogonalEdgeEditingPolicy.

The DeletingSelection and DeletedSelection events now use SelectionEventArgs<IModelItem>.

The constructor that take additional IGraph and IGraphSelection arguments have been removed, as well as the protected methods SetGraph, SetGraphControl, OnGraphChanged and the protected setter for the GraphSelection property. Instead, the IGraph instance is now always taken from the InputModeContext and cannot be changed after the mode is installed.

The CreateDefaultLabelConfiguration method has been removed.

The MarqueeSelect<T>(RectD,IEnumerable<T>) method has been removed.

The SelectionModel property has been removed. Instead the GraphSelection property is used.

The CollectionModel property has been removed. Instead the model items of the Graph property are used.

The GraphInputModeController property has been removed.

The protected event handlers for ClickInputMode's Clicked and DoubleClicked events have been removed.

FindItem has been removed. An additional overload of FindItems without the context parameter has been added. To replicate the previous behavior of FindItem, FindItems can be called and the first element taken from the resulting enumeration.

ShouldBeMovableForMoveInputMode has been removed.

Improved GraphViewerInputMode API:

Added support for the Copy command.

Added support for multi-selection via Ctrl+Click and marquee selection. The latter is disabled by default.

The click hit-test order can now be configured by property ClickHitTestOrder.

By default, clipboard commands are now disabled. This can be controlled with the new property AllowClipboardOperations.

The ItemSelected event has been removed.

ClipboardCommandsEnabled has been removed.

CreateEdgeInputMode

CreateEdgeInputMode has been refactored and streamlined:

Orthogonal edge creation is automatically enabled if orthogonal edge editing is enabled on the containing GraphEditorInputMode.

The ConnectToCandidatesOnly property has been removed. Edge creation now always uses port candidates.

The creation callbacks NodeBasedEdgeCreationCallback and PortBasedEdgeCreationCallback have been replaced by the new EdgeCreator which is always port-based.

The methods GetSourcePortOwner, GetTargetPortOwner, GetSourceNode and GetTargetNode have been replaced by GetSource and GetTarget.

The properties SourcePortCandidate and TargetPortCandidate are no longer read-only.

The methods DetermineEdgeStyle, AssignSourcePortPosition, AssignEdgeStyle as well as the EdgeStyle property have been removed. Instead the new EdgeDefaults property can be used to customize the new edge.

The UseHitNodeTargetCandidatesOnly property has been replaced by the new UseHitItemsCandidatesOnly property.

The type of the OrthogonalEdgeCreation property has been changed from bool to OrthogonalEdgeEditingPolicy.

The new DummyEdgeGraph property is used to create the dummy edge that visualizes the edge during creation.

The preview edge which is displayed during edge creation now shows the edge as it will be created, i.e. the preview edge has the same style, port visualization, and labels as the created edge will have.

The SnapToTargetCandidateOwner property has been removed. The preview edge now is always being cropped at the candidate owner's borders.

A new CancelGestureOnInvalidTarget property has been added that makes it possible to cancel the gesture immediately if ended on an invalid target.

The EdgeCreator callback now has a templateEdge parameter where all data for edge creation can be retrieved from. The source and target IPort parameters have been changed to IPortCandidates.

The AssignBends method has been removed and its functionality folded into the default EdgeCreator implementation. This also means that customized EdgeCreators now have to add bends to the created edge as well.

The following methods have been removed: IsPortCandidateResolutionEnabled, IsValidEnd, IsValidBegin, IsCancelGesture, IsBendCreationEnforced, IsValidBend, IsSourceNodeDraggingFinished, IsRemoveBendEvent. Instead, use the corresponding ...EventRecognizer properties to customize the behavior.

The following methods and properties have been removed: CreateBend(PointD), StartCreateEdge, OnTargetLocationChanged, GetNodes, NodeComparer and PortOwnerComparer.

Other Input Modes

AbstractContextMenuInputMode: Support for different context menu trigger events has been added. Currently only mouse (right-click) and keyboard (application / context menu key) are distinguished, more may be added in the future.

ClickInputMode: The ValidClickHitCursor property has been added. This cursor is used when hovering over a valid hit region.

ClickInputMode: The PreventNextDoubleClick method has been added that can be used in event handlers for single clicks to prevent that this click can become part of a double click event.

CreateBendInputMode: The CancelEventRecognizer property has been removed.

HandleInputMode: The Active property has been removed. The mode can be manually deactivated using the Enabled property instead.

HandleInputMode: The Arm method now has a handle parameter for the handle that is under the mouse cursor.

NodeDropInputMode: The NodeCreator callback, NodeCreated event, and GetDraggedNode method have been removed. The ItemCreator callback, ItemCreated event and DraggedItem property from its base class ItemDropInputMode is used instead.

OverviewInputMode now extends MultiplexingInputMode and can be customized more easily. Minor modes can be replaced and adjusted, as well as the list of available default command bindings can be modified.

OverviewInputMode: The new Margins property specifies margins for the visible area of the bound GraphOverviewControl. The new protected method UpdateVisibleArea provides further means for customizing the visible area.

MarqueeSelectionInputMode: The events DragStarting, DragStarted, Dragging, Dragged, DragFinishing, DragFinished, DragCanceling and DragCanceled now use MarqueeSelectionEventArgs that provide the current selection rectangle.

MarqueeSelectionInputMode: The MarqueeSelected event has been removed. The DragFinished event can be used instead.

MarqueeSelectionInputMode: The LastModifierState property has been removed.

MoveInputMode now provides a QueryPositionHandler event that queries an IPositionHandler each time a drag is started.

MoveViewportInputMode: Mouse cursor handling is now also done by protected methods Arm and Disarm, similar to other input modes.

MultiplexingInputMode: The ChildController property and CreateChildConcurrencyController method have been removed.

TableEditorInputMode: The new events LabelAdding and LabelEditing allow fine-grained control over adding or editing labels and tie into the existing functionality provided by IEditLabelHelper.

TableEditorInputMode: The events DeletingSelection and DeletedSelection now use SelectionEventArgs<IStripe>.

TableEditorInputMode: Now contains the AllowMixedSelection property which has been moved from the removed class CompositeStripeSelection.

WaitInputMode.GetMultiplexingInputMode has been removed.

TextEditorInputMode: The events EditingStarted, EditingCanceled and TextEdited now use TextEventArgs.

TextEditorInputMode: The properties StopRecognizer, CancelRecognizer and LineBreakRecognizer have been added which allow for easy customization of the key gestures used to add new line breaks and to cancel or stop the text editing.

Label Editing

IEditLabelHelper has been refactored:

AddLabel and EditLabel have been replaced by the methods OnLabelAdding and OnLabelEditing which take the new LabelEditingEventArgs as their only argument.

The IEditLabelHelper.ConfigureTextEditorInputMode method has been removed. It has been replaced by the LabelEditingEventArgs.TextEditorInputModeConfigurator property.

The customizations possible from IEditLabelHelper are the same as those from the LabelAdding and LabelEditing events on GraphEditorInputMode and TableEditorInputMode. IEditLabelHelper is conceptually used as another event handler for those events.

The Owner property of EditLabelHelper has been removed, along with the respective constructor. The label owner can usually be queried from the LabelEditingEventArgs. Custom subclasses can of course still opt to store the item they were created for and use that field.

If an IEditLabelHelper implementation is present in an ILabeledItem's lookup, its AddLabel method is called to determine whether a label may be added and provide a suitable label instance. Additionally, the predicate method GraphEditorInputMode.ShouldLabelBeAdded always has to return true, whether edit helpers are present or not. If the new label should be edited interactively after it's creation (the default behavior), it also must be editable, following the rules above. Therefore an IEditLabelHelper implementation usually should allow editing of label instances that it has created itself in OnLabelAdding.

The current label visual can be hidden while the text editor is shown to reduce visual clutter. This feature is enabled by default and can be controlled through the GraphEditorInputMode.HideLabelDuringEditing property.

Snapping

SnapContext:

A boolean parameter snappingDisabled has been added to the methods HandleMove and DragFinished. This parameter has to be set to true to handle moves or finish a drag when snapping is temporarily disabled. This replaces the call to SnapContext.DisableSnapping.

The events Initializing, Initialized and CleanedUp as well as their associated methods now use InputModeEventArgs.

The VoidInstance field has been removed.

GraphSnapContext:

The return type of GetMovementInfos has been changed to IListEnumerable<MovementInfo> and the classes NodeMovementInfo, PortMovementInfo, BendMovementInfo and EdgeEndMovementInfo have been removed.

The info parameter's type of AddEdgeEndToBeMoved has been changed to the more general MovementInfo. A boolean parameter AtSource has been added.

The methods AddSameWidthEntries and AddSameHeightEntries now return an IListEnumerable<RectD> containing the rectangles whose widths respectively heights are closest to the given size. The parameters resultingSize and rects have been removed.

IEdgeSnapResultProvider:

The methods InitializeSnapping and CleanupSnapping have been removed.

The info parameter's type of CollectSnapResults has been changed to IListEnumerable<MovementInfo>.

SnapResult now has more factory methods. The class SnapLineSnapResult has been replaced with a factory method as well.

The classes SnapLineContainer, SingleLineSnapLineContainer, EdgeSegmentSnapLineContainer, FixedDistanceSnapLineContainer, InBetweenSnapLineContainer have been removed.

Clipboard

The GraphClipboard.ClipboardContext property has been removed.

The Copy methods in GraphCopier now have a new PointDoffset parameter that shifts nodes and bends by a given amount upon copying them.

The signature of IClipboardIdProvider.GetId has changed. The context parameter has been moved to the front.

KeyboardInputMode

KeyboardInputMode has been simplified along with all helper types and infrastructure around commands:

KeyboardInputMode now allows creating a mapping between a key gesture and a command as well as providing custom execution logic for a given command.

There is also a single new method RemoveCommand on KeyboardInputMode which removes all currently existing bindings for a given command.

Various Input-related Changes

Events

The properties LastMouse2DEventArgs and LastEventLocation have been removed from all input modes. Instead, the properties LastMouseEvent and LastEventLocation on CanvasControl can be used.

EdgeEventArgs now also contains the owner of the source and target port.

ItemClickedEventArgs now also contains the location of the click.

StripeEventArgs now also contains the Table for this event.

OrthogonalEdgeEditingContext: The events Initializing, Initialized and CleanedUp as well as associated methods now use InputModeEventArgs.

GraphCommands.AdjustGroupNodeSize now always processes the nodes in bottom to top order instead of using the order in which the nodes were selected.

All hit-testing methods as well as the methods in IPortSelectionTester and IBendSelectionTester now take an IInputModeContext instead of ICanvasContext as their context parameter.

IPositionHandler.SetPosition has been removed. The interface is now used as a flagging interface only.

The classes DefaultPositionHandler and PointHandle have been removed.

GraphEditorInputMode.NodeCreator now has an additional parent parameter which can be used as the parent node for creating a new node. GraphEditorInputMode tries to find a group node at the click location to pass as parent to the NodeCreator.

Opening a context menu from the keyboard no longer uses the last known mouse pointer location for opening the context menu. Instead, the location of the current selection or the current item are used.

IPortCandidateProvider: The two method overloads GetSourcePortCandidatesForEdge and GetTargetPortCandidatesForEdge that had an IEdge parameter have been removed - the two remaining pairs have been merged into a single method with an optional argument for the opposite candidate.

The property AbstractPortCandidateProvider.PortOwner has been removed, along with the methods that made use of it.

AbstractPortCandidateProvider: Overloads of CreateCandidate taking an IPort an optionally an IPortLocationModel have been removed.

DefaultPortCandidate: A constructor overload taking the optional PortCandidateValidity additionally has been added.

OrthogonalEdgeEditingContext.AddMovedEdgeEnd: The movementInfo parameter's type has been changed to the more general MovementInfo. A boolean parameter atSource has been added.

PortRelocationHandle: The method ConfigureDummyEdge has been folded into CreateDummyEdge.

The methods IDragHandler.HandleMove and IReshapeHandler.HandleReshape no longer has a return value.

The classes InputModeController and GraphInputModeController have been removed.

The abstract class EdgeEndMoveHandle has been removed.

The StateMachine class as well as the associated types and infrastructure have been removed from the API.

GraphML

The XML namespaces have been updated and the mapping from yFiles WPF types to their corresponding XML namespace has been changed.

All platform-independent graph model types are now mapped to http://www.yworks.com/xml/yfiles-common/3.0. This includes the following types:

all graph item types

all default label models

all port location models

all "void" styles

serialization for geometric primitives

All platform-independent GraphML support types are now mapped to http://www.yworks.com/xml/yfiles-common/markup/3.0.

All platform-independent framework classes are now mapped to http://www.yworks.com/xml/yfiles-common/markup/primitives/2.0. This includes the following types:

Built-in value types (int, double, bool, etc., and enumeration types)

string

All library types specific to yFiles WPF are now mapped to http://www.yworks.com/xml/yfiles-for-html/2.0/xaml. These are mainly the types in the following namespaces:

yWorks.Graph.Styles

yWorks.Markup.Platform

The following events have been added to signal the end of the write or parse process, respectively: GraphMLIOHandler.Parsed, GraphMLParser.Parsed, GraphMLIOHandler.Written, GraphMLWriter.Written, together with the corresponding event raiser methods.

SerializationProperties:

The new serialization property ParseLabelSize optionally disables parsing of the preferred size of a label. This can be used to prevent unexpected clipping when parsing GraphML written on different machines, or with fonts that are not available.

WriteGraphSettings and DisableGraphSettings have been merged to a single DisableGraphSettings property which is interpreted according to the context where it is set.

IndentOutput has been added that allows to define whether the XML output should be properly indented.

A few abstract base classes have been merged:

AbstractXmlWriter and DirectXmlWriter have been merged into XmlWriter

AbstractMapperInputHandler and ComplexMapperInputHandler have been merged into MapperInputHandler

AbstractMapperOutputHandler and ComplexMapperOutputHandler have been merged into MapperOutputHandler

The legacy interface IDeserializer has been removed. For custom deserialization an event handler for GraphMLIOHandler.HandleDeserialization can be used.

The classes ArrayValueSerializer and NullXmlWriter have been removed.

IXamlNameMapper has been refactored to and AddXamlNamespaceMapping has been added to GraphMLIOHandler.

QueryOutputHandlersEventArgs: The overload of AddOutputHandler taking an object id has been removed.

XmlWriter: A property indent has been added that allow to define whether the XML output should be properly indented.

XmlWriter: The constructor overload taking an InternalXmlWriter as well as the corresponding property DelegateWriter have been removed.

Utility Types

A lot of the utility types have been either replaced or removed.

The yWorks.Model namespace has been removed and its types have been moved to more intuitive namespaces.

The yWorks.Support namespace has been removed along with most of the types contained within, since they were not really needed. The remaining types have been moved to more meaningful namespaces, mainly yWorks.Controls.

The classes CompositeHandle<T> and CompositePositionHandler have been removed.

The IMapper.RemoveValue method has been removed. It depends on the specific implementation of the mapper whether a mapping can be removed. If an implementation provides a way to remove a mapping, that should be preferred over setting a null value.

The classes GenericYList, GenericListCell, and HashSet have been removed.

The classes DefaultNodeLookup, DefaultEdgeLookup, DefaultPortLookup, DefaultLabelLookup, DefaultBendLookup and DefaultItemLookup have been removed. Properties with the same names have been added to DefaultGraph instead.

The ItemDecorator<TModelItem> class has been removed. Its members have been pushed down to its former sub-classes NodeDecorator, EdgeDecorator, LabelDecorator, PortDecorator, and BendDecorator.

The events ItemSelected and ItemDeselected on ISelectionModel have been merged into the ItemSelectionChanged event.

The GeomSupport.CreateSmoothedPath method has been moved to GeneralPath.

Layout

Layout Execution

LayoutExecutor:

The method Stop now stops a running layout calculation as soon as possible and then immediately shows the result so far, skipping any animation. In addition, the new method Cancel immediately cancels a running calculation and doesn't change the GraphControl's Graph unless the animation was already running.

The property AbortHandler has been made read-only. There is a protected factory method CreateAbortHandler which can be overridden to create a custom AbortHandler implementation.

Labels are now taken into account for the final content rectangle and viewport animation.

The new property ConsiderViewportLimiter can be enabled to let the target viewport after a layout respect the ViewportLimiter of the GraphControl. The ViewportAnimation has a new property ConsiderViewportLimiter for the same purpose.

The classes LayoutExecutor and LayoutGraphAdapter now have a property AutomaticEdgeGrouping that automatically configures edge groups for ports with multiple incoming or outgoing edges. This feature is enabled by default.

The classes LayoutExecutor and LayoutGraphAdapter now have a property FixPorts that automatically configures strong source and target port constraints for all edges in the graph. This feature is disabled by default.

LayoutExecutor no longer throws an exception wrapping a layout exception if no event handler of LayoutFinished handled the event arguments. This means that exceptions in a layout algorithm can go by unnoticed if the layout runs asynchronously, and the task returned from LayoutExecutor.Start is not awaited.

LayoutGraphAdapter now adds data providers that map each node, edge, and label of a LayoutGraph to their corresponding IModelItem in the original IGraph. Especially, these data providers are available if a layout is run with a LayoutExecutor or the convenience methods MorphLayout or ApplyLayout.

Layout API

The legacy hierarchic layout algorithms HierarchicLayouter, HierarchicGroupLayouter, and the associated legacy interfaces ILayerer, IDrawer, IMementoSupport, ILayerSequencer, together with their implementations, have been removed. Instead, IncrementalHierarchicLayouter has been renamed to HierarchicLayout and is now the only implementation of the hierarchic layout style. All associated interfaces and implementations from the namespace yWorks.yFiles.Layout.Hierarchic.Incremental have been moved up to yWorks.Layout.Hierarchic.

The legacy classes OrthogonalGroupLayouter and DirectedOrthogonalLayouter have been removed and their features have been incorporated into OrthogonalLayout.

The legacy class OrthogonalEdgeRouter and all associated classes have been removed.

The HVTreeLayouter class has been removed and its features have been incorporated into TreeLayout.

The DefaultGraphLayout class has been removed.

The ParentEdgeAugmentationStage class has been removed.

The Graph.MoveSubgraph method has been removed.

CopiedLayoutIGraph has been removed. An instance of the base type CopiedLayoutGraph with the same functionality can be obtained from LayoutGraphAdapter's CreateCopiedLayoutGraph factory method.

The CanLayout method has been removed from all layout algorithms. Previously it pretty much always returned true.