com.yworks.yfiles.view

Class BridgeManager

java.lang.Object

com.yworks.yfiles.view.BridgeManager

public class BridgeManager
extends Object

Helper class that calculates visual hints in a path where said path crosses an obstacle.

Most notably this feature is used to render crossings of IEdges with other edges.

To set up bridges in a GraphControl at the least the following is necessary:

Furthermore, an edge style that supports bridges is necessary; PolylineEdgeStyle is a good choice. Various other properties can be set to change the defaults, e.g. how bridges appear, or which way bridges point.

Constructor Summary

Constructors

Constructor and Description
BridgeManager() Initializes a new instance of the BridgeManager class.

Method Summary

Modifier and Type	Method and Description
GeneralPath	addBridges(IRenderContext context, GeneralPath path, IBridgeCreator callback) Core method that will add bridges to a GeneralPath using the IBridgeCreator callback to determine the type of the bridges.
void	addObstacleProvider(IObstacleProvider provider) Adds another IObstacleProvider to query for obstacles.
void	dispose() Disposes of this instance by resetting the CanvasControl property to null.
BridgeCrossingPolicy	getBridgeCrossingPolicy() Gets the BridgeCrossingPolicy mode that is used by this instance.
CanvasControl	getCanvasControl() Gets the CanvasControl that should be managed by this instance.
double	getClipMargin() Gets the margin by which the Clip should be enlarged to accommodate for clipped away lines being taken into account for bridge calculation.
IBridgeCreator	getDefaultBridgeCreator() Gets the default implementation of the IBridgeCreator that will be used if addBridges(IRenderContext, GeneralPath, IBridgeCreator) is invoked with a null callback argument.
BridgeCrossingStyle	getDefaultBridgeCrossingStyle() Gets the default BridgeCrossingStyle that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
double	getDefaultBridgeHeight() Gets the default height of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
BridgeOrientationStyle	getDefaultBridgeOrientationStyle() Gets the default BridgeOrientationStyle for bridges that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
double	getDefaultBridgeWidth() Gets the default width of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
long	getObstacleHash(IRenderContext context) Gets a hash code that describes the current state of the obstacles.
double	getZoomThreshold() Gets a threshold value that determines below which zoom level, there should be no more bridge calculation.
void	insertDefaultCustomBridge(IRenderContext context, GeneralPath path, PointD start, PointD end, double gapLength) Implementation that will be called by the default value of the DefaultBridgeCreator to satisfy requests to IBridgeCreator.createCustomBridge(IRenderContext, GeneralPath, PointD, PointD, double).
protected void	install(CanvasControl canvas) Installs this manager for the specified CanvasControl.
boolean	isCurvesConsiderationEnabled() Gets a value that determines whether curves (cubic and quadratic) should be considered as obstacles.
void	registerObstacle(IRenderContext context, GeneralPath path) Convenience method that can be called to dynamically register an obstacle path with the context during the rendering.
void	registerObstacleCubicCurve(IRenderContext context, PointD p1, PointD cp1, PointD cp2, PointD p2) Convenience method that can be called to dynamically register a single obstacle cubic curve with the context during the rendering.
void	registerObstacleLine(IRenderContext context, PointD p1, PointD p2) Convenience method that can be called to dynamically register a single obstacle line with the context during the rendering.
void	registerObstacleQuadCurve(IRenderContext context, PointD p1, PointD cp, PointD p2) Convenience method that can be called to dynamically register a single obstacle quadratic curve with the context during the rendering.
protected void	registerObstacles(IRenderContext context) Called to initialize the context with the obstacles.
void	removeObstacleProvider(IObstacleProvider provider) Removes a previously added IObstacleProvider from the list of registered providers.
void	setBridgeCrossingPolicy(BridgeCrossingPolicy value) Sets the BridgeCrossingPolicy mode that is used by this instance.
void	setCanvasControl(CanvasControl value) Sets the CanvasControl that should be managed by this instance.
void	setClipMargin(double value) Sets the margin by which the Clip should be enlarged to accommodate for clipped away lines being taken into account for bridge calculation.
void	setCurvesConsiderationEnabled(boolean value) Sets a value that determines whether curves (cubic and quadratic) should be considered as obstacles.
void	setDefaultBridgeCreator(IBridgeCreator value) Sets the default implementation of the IBridgeCreator that will be used if addBridges(IRenderContext, GeneralPath, IBridgeCreator) is invoked with a null callback argument.
void	setDefaultBridgeCrossingStyle(BridgeCrossingStyle value) Sets the default BridgeCrossingStyle that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
void	setDefaultBridgeHeight(double value) Sets the default height of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
void	setDefaultBridgeOrientationStyle(BridgeOrientationStyle value) Sets the default BridgeOrientationStyle for bridges that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
void	setDefaultBridgeWidth(double value) Sets the default width of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.
void	setZoomThreshold(double value) Sets a threshold value that determines below which zoom level, there should be no more bridge calculation.
protected void	uninstall(CanvasControl canvas) Reverts the install(CanvasControl) method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BridgeManager

public BridgeManager()

Initializes a new instance of the BridgeManager class.

Initially the DefaultBridgeCreator will be set to an instance that will delegate to the set of Default properties in this class and the insertDefaultCustomBridge(IRenderContext, GeneralPath, PointD, PointD, double) method respectively.

Method Detail

addBridges

public GeneralPath addBridges(IRenderContext context,
                              GeneralPath path,
                              IBridgeCreator callback)

Core method that will add bridges to a GeneralPath using the IBridgeCreator callback to determine the type of the bridges.

This method may return path itself if no crossings have been determined. Otherwise it will return a new path instance that has the bridges added at the corresponding places.

Parameters:

context - The context to use.

path - The path to calculate the bridged variant for.

callback - The callback or null that determines the appearance of the bridges.

Returns:

The path that might have been augmented by the bridges.

addObstacleProvider

public void addObstacleProvider(IObstacleProvider provider)

Adds another IObstacleProvider to query for obstacles.

The IObstacleProvider.getObstacles(IRenderContext) method will be invoked during construction of the obstacles.

Parameters:

provider - The provider instance to use for later queries.

See Also:

registerObstacles(IRenderContext), removeObstacleProvider(IObstacleProvider)

dispose

public void dispose()

Disposes of this instance by resetting the CanvasControl property to null.

getBridgeCrossingPolicy

public final BridgeCrossingPolicy getBridgeCrossingPolicy()

Gets the BridgeCrossingPolicy mode that is used by this instance.

By default the BridgeCrossingPolicy.HORIZONTAL_BRIDGES_VERTICAL mode is set.

Returns:

The BridgeCrossingPolicy.

See Also:

setBridgeCrossingPolicy(BridgeCrossingPolicy)

getCanvasControl

public final CanvasControl getCanvasControl()

Gets the CanvasControl that should be managed by this instance.

This method will install(CanvasControl) a preparation stage for the IRenderContext in the provided CanvasControl via the ILookup.lookup(Class) mechanism.

Returns:

The CanvasControl.

See Also:

setCanvasControl(CanvasControl)

getClipMargin

public final double getClipMargin()

Gets the margin by which the Clip should be enlarged to accommodate for clipped away lines being taken into account for bridge calculation.

This value should be set to at least half the value of the width of the bridges used in this context. This is because obstacles might otherwise be clipped from the view and not taken into account for the calculation of the bridges. By default this value will be 2 more than half of the DefaultBridgeWidth.

Returns:

The ClipMargin.

See Also:

setClipMargin(double)

getDefaultBridgeCreator

public final IBridgeCreator getDefaultBridgeCreator()

Gets the default implementation of the IBridgeCreator that will be used if addBridges(IRenderContext, GeneralPath, IBridgeCreator) is invoked with a null callback argument.

Returns:

The DefaultBridgeCreator.

See Also:

getDefaultBridgeCrossingStyle(), getDefaultBridgeWidth(), getDefaultBridgeHeight(), insertDefaultCustomBridge(IRenderContext, GeneralPath, PointD, PointD, double), setDefaultBridgeCreator(IBridgeCreator)

getDefaultBridgeCrossingStyle

public final BridgeCrossingStyle getDefaultBridgeCrossingStyle()

Gets the default BridgeCrossingStyle that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default value is BridgeCrossingStyle.ARC.

Returns:

The DefaultBridgeCrossingStyle.

See Also:

IBridgeCreator.getCrossingStyle(IRenderContext), setDefaultBridgeCrossingStyle(BridgeCrossingStyle)

getDefaultBridgeHeight

public final double getDefaultBridgeHeight()

Gets the default height of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default value is 5.0d.

Returns:

The DefaultBridgeHeight.

See Also:

IBridgeCreator.getBridgeHeight(IRenderContext), setDefaultBridgeHeight(double)

getDefaultBridgeOrientationStyle

public final BridgeOrientationStyle getDefaultBridgeOrientationStyle()

Gets the default BridgeOrientationStyle for bridges that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default is BridgeOrientationStyle.UP.

Returns:

The DefaultBridgeOrientationStyle.

See Also:

IBridgeCreator.getOrientationStyle(IRenderContext), setDefaultBridgeOrientationStyle(BridgeOrientationStyle)

getDefaultBridgeWidth

public final double getDefaultBridgeWidth()

Gets the default width of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default value is 10.0d. Setting this value will adjust the ClipMargin.

Returns:

The DefaultBridgeWidth.

See Also:

IBridgeCreator.getBridgeWidth(IRenderContext), setDefaultBridgeWidth(double)

getObstacleHash

public long getObstacleHash(IRenderContext context)

Gets a hash code that describes the current state of the obstacles.

This method can be used to get a concise, digest snapshot of the current obstacle locations. Storing that result and comparing it to another snapshot later allows to determine quickly whether obstacles have changed since the last call. This is helpful, e.g. in implementations of IEdgeStyle that support bridges to not recreate the edge path (including bridges) in IVisualCreator.updateVisual(IRenderContext, javafx.scene.Node) if no obstacles changed.

Parameters:

context - The context to inspect.

Returns:

A hash of the state of the obstacles.

getZoomThreshold

public final double getZoomThreshold()

Gets a threshold value that determines below which zoom level, there should be no more bridge calculation.

Since the calculation of the bridges is a costly operation if there are many items visible and bridges are not clearly visible at low zoom levels, it is convenient to disable the calculation of bridges for these zoom levels to speed up the rendering process. The default value is 0.3d.

Returns:

The ZoomThreshold.

See Also:

setZoomThreshold(double)

insertDefaultCustomBridge

public void insertDefaultCustomBridge(IRenderContext context,
                                      GeneralPath path,
                                      PointD start,
                                      PointD end,
                                      double gapLength)

Implementation that will be called by the default value of the DefaultBridgeCreator to satisfy requests to IBridgeCreator.createCustomBridge(IRenderContext, GeneralPath, PointD, PointD, double).

This implementation will insert a gap style bridge by first creating a line to start and then moving to end.

Parameters:

context - The context for the call.

path - The path to append the next segment to.

start - The coordinates of the starting point of the bridge.

end - The coordinates of the ending point of the bridge.

gapLength - The distance between the starting point and the end point.

See Also:

IBridgeCreator.createCustomBridge(IRenderContext, GeneralPath, PointD, PointD, double)

install

protected void install(CanvasControl canvas)

Installs this manager for the specified CanvasControl.

Parameters:

canvas - The CanvasControl.

isCurvesConsiderationEnabled

public final boolean isCurvesConsiderationEnabled()

Gets a value that determines whether curves (cubic and quadratic) should be considered as obstacles.

This can be a costly operation so the default is false.

Returns:

The CurvesConsiderationEnabled.

See Also:

setCurvesConsiderationEnabled(boolean)

registerObstacle

public void registerObstacle(IRenderContext context,
                             GeneralPath path)

Convenience method that can be called to dynamically register an obstacle path with the context during the rendering.

Normally all obstacles will be registered initially by method registerObstacles(IRenderContext). This method can be called during the rendering phase to register additional obstacles at a later point in time.

Parameters:

context - The context to register the obstacles with.

path - The path that describes the obstacles.

See Also:

registerObstacleLine(IRenderContext, PointD, PointD)

registerObstacleCubicCurve

public void registerObstacleCubicCurve(IRenderContext context,
                                       PointD p1,
                                       PointD cp1,
                                       PointD cp2,
                                       PointD p2)

Convenience method that can be called to dynamically register a single obstacle cubic curve with the context during the rendering.

Normally all obstacles will be registered initially by method registerObstacles(IRenderContext). This method can be called during the rendering phase to register additional obstacles at a later point in time.

Parameters:

context - The context to register the obstacles with.

p1 - The coordinates of the starting point of the line.

cp1 - The coordinates of the first control point of the curve.

cp2 - The coordinates of the second control point of the curve.

p2 - The coordinates of the ending point of the line.

See Also:

registerObstacleLine(IRenderContext, PointD, PointD)

registerObstacleLine

public void registerObstacleLine(IRenderContext context,
                                 PointD p1,
                                 PointD p2)

Convenience method that can be called to dynamically register a single obstacle line with the context during the rendering.

Normally all obstacles will be registered initially by method registerObstacles(IRenderContext). This method can be called during the rendering phase to register additional obstacles at a later point in time.

Parameters:

context - The context to register the obstacles with.

p1 - The coordinates of the first point of the line.

p2 - The coordinates of the second point of the line.

See Also:

registerObstacleLine(IRenderContext, PointD, PointD)

registerObstacleQuadCurve

public void registerObstacleQuadCurve(IRenderContext context,
                                      PointD p1,
                                      PointD cp,
                                      PointD p2)

Convenience method that can be called to dynamically register a single obstacle quadratic curve with the context during the rendering.

Normally all obstacles will be registered initially by method registerObstacles(IRenderContext). This method can be called during the rendering phase to register additional obstacles at a later point in time.

Parameters:

context - The context to register the obstacles with.

p1 - The coordinates of the starting point of the line.

cp - The coordinates of the control point of the curve.

p2 - The coordinates of the ending point of the line.

See Also:

registerObstacleLine(IRenderContext, PointD, PointD)

registerObstacles

protected void registerObstacles(IRenderContext context)

Called to initialize the context with the obstacles.

Parameters:

context - The context that will be used to store the obstacles with.

See Also:

registerObstacle(IRenderContext, GeneralPath), registerObstacleLine(IRenderContext, PointD, PointD)

removeObstacleProvider

public void removeObstacleProvider(IObstacleProvider provider)

Removes a previously added IObstacleProvider from the list of registered providers.

Parameters:

provider - The provider instance to remove from this instance.

See Also:

addObstacleProvider(IObstacleProvider)

setBridgeCrossingPolicy

public final void setBridgeCrossingPolicy(BridgeCrossingPolicy value)

Sets the BridgeCrossingPolicy mode that is used by this instance.

By default the BridgeCrossingPolicy.HORIZONTAL_BRIDGES_VERTICAL mode is set.

Parameters:

value - The BridgeCrossingPolicy to set.

See Also:

getBridgeCrossingPolicy()

setCanvasControl

public final void setCanvasControl(CanvasControl value)

Sets the CanvasControl that should be managed by this instance.

This method will install(CanvasControl) a preparation stage for the IRenderContext in the provided CanvasControl via the ILookup.lookup(Class) mechanism.

Parameters:

value - The CanvasControl to set.

See Also:

getCanvasControl()

setClipMargin

public final void setClipMargin(double value)

Sets the margin by which the Clip should be enlarged to accommodate for clipped away lines being taken into account for bridge calculation.

This value should be set to at least half the value of the width of the bridges used in this context. This is because obstacles might otherwise be clipped from the view and not taken into account for the calculation of the bridges. By default this value will be 2 more than half of the DefaultBridgeWidth.

Parameters:

value - The ClipMargin to set.

See Also:

getClipMargin()

setCurvesConsiderationEnabled

public final void setCurvesConsiderationEnabled(boolean value)

Sets a value that determines whether curves (cubic and quadratic) should be considered as obstacles.

This can be a costly operation so the default is false.

Parameters:

value - The CurvesConsiderationEnabled to set.

See Also:

isCurvesConsiderationEnabled()

setDefaultBridgeCreator

public final void setDefaultBridgeCreator(IBridgeCreator value)

Sets the default implementation of the IBridgeCreator that will be used if addBridges(IRenderContext, GeneralPath, IBridgeCreator) is invoked with a null callback argument.

Parameters:

value - The DefaultBridgeCreator to set.

See Also:

getDefaultBridgeCrossingStyle(), getDefaultBridgeWidth(), getDefaultBridgeHeight(), insertDefaultCustomBridge(IRenderContext, GeneralPath, PointD, PointD, double), getDefaultBridgeCreator()

setDefaultBridgeCrossingStyle

public final void setDefaultBridgeCrossingStyle(BridgeCrossingStyle value)

Sets the default BridgeCrossingStyle that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default value is BridgeCrossingStyle.ARC.

Parameters:

value - The DefaultBridgeCrossingStyle to set.

See Also:

IBridgeCreator.getCrossingStyle(IRenderContext), getDefaultBridgeCrossingStyle()

setDefaultBridgeHeight

public final void setDefaultBridgeHeight(double value)

Sets the default height of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default value is 5.0d.

Parameters:

value - The DefaultBridgeHeight to set.

See Also:

IBridgeCreator.getBridgeHeight(IRenderContext), getDefaultBridgeHeight()

setDefaultBridgeOrientationStyle

public final void setDefaultBridgeOrientationStyle(BridgeOrientationStyle value)

Sets the default BridgeOrientationStyle for bridges that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default is BridgeOrientationStyle.UP.

Parameters:

value - The DefaultBridgeOrientationStyle to set.

See Also:

IBridgeCreator.getOrientationStyle(IRenderContext), getDefaultBridgeOrientationStyle()

setDefaultBridgeWidth

public final void setDefaultBridgeWidth(double value)

Sets the default width of a bridge that will be used by the default implementation of the IBridgeCreator that is initially assigned to the DefaultBridgeCreator property.

The default value is 10.0d. Setting this value will adjust the ClipMargin.

Parameters:

value - The DefaultBridgeWidth to set.

See Also:

IBridgeCreator.getBridgeWidth(IRenderContext), getDefaultBridgeWidth()

setZoomThreshold

public final void setZoomThreshold(double value)

Sets a threshold value that determines below which zoom level, there should be no more bridge calculation.

Since the calculation of the bridges is a costly operation if there are many items visible and bridges are not clearly visible at low zoom levels, it is convenient to disable the calculation of bridges for these zoom levels to speed up the rendering process. The default value is 0.3d.

Parameters:

value - The ZoomThreshold to set.

See Also:

getZoomThreshold()

uninstall

protected void uninstall(CanvasControl canvas)

Reverts the install(CanvasControl) method.

Parameters:

canvas - The CanvasControl.