Package org.eclipse.gef.fx.nodes

Class InfiniteCanvas

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
org.eclipse.gef.fx.nodes.InfiniteCanvas
All Implemented Interfaces:
javafx.css.Styleable, EventTarget
public class InfiniteCanvas extends Region
An InfiniteCanvas provides a means to render a portion of a hypothetically infinite canvas, on which arbitrary contents can be placed. 
 +----------------+
 |content area    |
 |                |
 |         +----------------+
 |         |visible area    |
 |         |                |
 |         +----------------+
 |                |
 +----------------+

The size of the InfiniteCanvas itself determines the visible area, i.e. it is reflected in its Node.layoutBoundsProperty(). The content area is determined by the (visible) bounds of the getContentGroup() that contains the content elements. These bounds can be accessed via the contentBoundsProperty().

By default, scrollbars are shown when the content area exceeds the visible area. They allow to navigate the scrollableBoundsProperty(), which resembles the union of the content area and the visible area. The horizontal and vertical scroll offsets are controlled by the horizontalScrollOffsetProperty() and verticalScrollOffsetProperty(). The appearance of scrollbars can be controlled with the following properties:

An arbitrary transformation can be applied to the contents that is controlled by the contentTransformProperty(). It is unrelated to scrolling, i.e. translating the content does not change the scroll offset.

A background grid is rendered behind the contents per default. It always covers the complete visible area and can be enabled/disabled and customized via a set of properties:

Internally, an InfiniteCanvas consists of four layers: 

 +--------------------------------+
 |scrollbar group                 |
 +--------------------------------+
 |overlay group                   |
 +--------------------------------+
 |scrolled pane (with sub-layers) |
 +--------------------------------+
 |underlay group                  |
 +--------------------------------+
The getScrolledPane() internally consists of the following four sub-layers: 
 +--------------------------------+
 |scrolled overlay group          |
 +--------------------------------+
 |content group                   |
 +--------------------------------+
 |scrolled underlay group         |
 +--------------------------------+
 |grid canvas                     |
 +--------------------------------+

  • Property Details

  • Field Details

    • DEFAULT_GRID_POINT_COLOR

      public static final Color DEFAULT_GRID_POINT_COLOR
      The default Color that is used to draw grid points.

    • DEFAULT_GRID_CELL_WIDTH

      public static final int DEFAULT_GRID_CELL_WIDTH
      The default grid cell width.
      See Also:

    • DEFAULT_GRID_CELL_HEIGHT

      public static final int DEFAULT_GRID_CELL_HEIGHT
      The default grid cell height.
      See Also:

  • Constructor Details

    • InfiniteCanvas

      public InfiniteCanvas()
      Constructs a new InfiniteCanvas.

  • Method Details

    • clipContent

      protected void clipContent()
      Enables content clipping for this InfiniteCanvas.

    • clipContentProperty

      public BooleanProperty clipContentProperty()
      Returns the BooleanProperty that determines if this InfiniteCanvas does clipping, i.e. restricts its visibility to its Node.layoutBoundsProperty().
      See Also:

    • computeContentBoundsInLocal

      protected double[] computeContentBoundsInLocal()
      Computes the bounds [min-x, min-y, max-x, max-y] surrounding the content group within the coordinate system of this InfiniteCanvas.
      Returns:
      The bounds [min-x, min-y, max-x, max-y] surrounding the content group within the coordinate system of this InfiniteCanvas.

    • computeHv

      protected double computeHv(double tx)
      Converts a horizontal translation distance into the corresponding horizontal scrollbar value.
      Parameters:
      tx - The horizontal translation distance.
      Returns:
      The horizontal scrollbar value corresponding to the given translation.

    • computeScrollableBoundsInLocal

      protected double[] computeScrollableBoundsInLocal()
      Computes and returns the bounds of the scrollable area within this InfiniteCanvas.
      Returns:
      The bounds of the scrollable area, i.e. [minx, miny, maxx, maxy].

    • computeTx

      protected double computeTx(double hv)
      Converts a horizontal scrollbar value into the corresponding horizontal translation distance.
      Parameters:
      hv - The horizontal scrollbar value.
      Returns:
      The horizontal translation distance corresponding to the given scrollbar value.

    • computeTy

      protected double computeTy(double vv)
      Converts a vertical scrollbar value into the corresponding vertical translation distance.
      Parameters:
      vv - The vertical scrollbar value.
      Returns:
      The vertical translation distance corresponding to the given scrollbar value.

    • computeVv

      protected double computeVv(double ty)
      Converts a vertical translation distance into the corresponding vertical scrollbar value.
      Parameters:
      ty - The vertical translation distance.
      Returns:
      The vertical scrollbar value corresponding to the given translation.

    • contentBoundsProperty

      public ReadOnlyObjectProperty<Bounds> contentBoundsProperty()
      Provides the visual bounds of the content group in the local coordinate system of this InfiniteCanvas as a (read-only) property.
      See Also:

    • contentTransformProperty

      public ReadOnlyObjectProperty<Affine> contentTransformProperty()
      Returns the viewport transform as a (read-only) property.
      See Also:

    • createGrid

      protected Region createGrid()
      Creates the Region that renders the grid (when it is enabled).
      Returns:
      The newly created Region that renders the grid.

    • createGridTile

      protected Image createGridTile()
      Locate or create an Image that represents a single grid cell/tile. The Image's dimensions is expected to match the grid cell size (width and height).
      Returns:
      An Image that represents a single grid cell/tile.

    • createLayers

      protected List<? extends Node> createLayers()
      Returns a list containing the top level layers in the visualization of this InfiniteCanvas. Per default, the underlay group, the scrolled pane, the overlay group, and the scrollbar group are returned in that order.
      Returns:
      A list containing the top level layers in the visualization of this InfiniteCanvas.

    • createScrollBarGroup

      protected Group createScrollBarGroup()
      Creates the Group designated for holding the scrollbars and places the scrollbars in it. Furthermore, event listeners are registered to update the scroll offset upon scrollbar movement.
      Returns:
      The Group designated for holding the scrollbars.

    • createScrolledLayers

      protected List<? extends Node> createScrolledLayers()
      Returns a list containing the scrolled layers in the visualization of this InfiniteCanvas. Per default, the grid canvas, the scrolled underlay group, the content group, and the scrolled overlay group are returned in that order.
      Returns:
      A list containing the top level layers in the visualization of this InfiniteCanvas.

    • fitToSize

      public void fitToSize(double zoomMin, double zoomMax)
      Adjusts the horizontalScrollOffsetProperty(), the verticalScrollOffsetProperty(), and the contentTransformProperty(), so that the getContentGroup() is fully visible within the bounds of this InfiniteCanvas if possible. The content will be centered, but the given zoomMin and zoomMax values restrict the zoom factor, so that the content might exceed the canvas, or does not fill it completely.

      Note, that the contentTransformProperty() is set to a pure scale transformation by this method.

      Note, that fit-to-size cannot be performed in all situations. If the content area is 0 or the canvas area is 0, then this method cannot fit the content to the canvas size, and therefore, throws an IllegalStateException. The following condition can be used to test if fit-to-size can be performed: 

       if (infiniteCanvas.getWidth() > 0 && infiniteCanvas.getHeight() > 0
                && infiniteCanvas.getContentBounds().getWidth() > 0
                && infiniteCanvas.getContentBounds().getHeight() > 0) {
        // save to call fit-to-size here
        infiniteCanvas.fitToSize();
 }
      Parameters:
      zoomMin - The minimum zoom level.
      zoomMax - The maximum zoom level.
      Throws:
      IllegalStateException - when the content area is zero or the canvas area is zero.

    • getContentBounds

      public Bounds getContentBounds()
      Returns the value of the contentBoundsProperty().
      Returns:
      The value of the contentBoundsProperty().

    • getContentGroup

      public Group getContentGroup()
      Returns the Group designated for holding the scrolled content.
      Returns:
      The Group designated for holding the scrolled content.

    • getContentTransform

      public Affine getContentTransform()
      Returns the transformation that is applied to the content group.
      Returns:
      The transformation that is applied to the content group.

    • getGridCanvas

      protected Region getGridCanvas()
      Returns the Region that is used to paint the background grid.
      Returns:
      The Region that is used to paint the background grid.

    • getGridCellHeight

      public double getGridCellHeight()
      Returns the value of the gridCellHeightProperty().
      Returns:
      The value of the gridCellHeightProperty().

    • getGridCellWidth

      public double getGridCellWidth()
      Returns the value of the gridCellWidthProperty().
      Returns:
      The value of the gridCellWidthProperty().

    • getHorizontalScrollBar

      public ScrollBar getHorizontalScrollBar()
      Returns the horizontal ScrollBar, or null if the horizontal ScrollBar was not yet created.
      Returns:
      The horizontal ScrollBar.

    • getHorizontalScrollBarPolicy

      public ScrollPane.ScrollBarPolicy getHorizontalScrollBarPolicy()
      Returns the ScrollPane.ScrollBarPolicy that is currently used to decide when to show a horizontal scrollbar.
      Returns:
      The ScrollPane.ScrollBarPolicy that is currently used to decide when to show a horizontal scrollbar.

    • getHorizontalScrollOffset

      public double getHorizontalScrollOffset()
      Returns the current horizontal scroll offset.
      Returns:
      The current horizontal scroll offset.

    • getOverlayGroup

      public Group getOverlayGroup()
      Returns the overlay Group that is rendered above the contents but below the scrollbars.
      Returns:
      The overlay Group that is rendered above the contents but below the scrollbars.

    • getScrollableBounds

      public Bounds getScrollableBounds()
      Returns the value of the scrollableBoundsProperty().
      Returns:
      The value of the scrollableBoundsProperty().

    • getScrollBarGroup

      protected Group getScrollBarGroup()
      Returns the Group designated for holding the ScrollBars.
      Returns:
      The Group designated for holding the ScrollBars.

    • getScrolledOverlayGroup

      public Group getScrolledOverlayGroup()
      Returns the scrolled overlay Group.
      Returns:
      The scrolled overlay Group.

    • getScrolledPane

      protected Pane getScrolledPane()
      Returns the Pane which is translated when scrolling. This Pane contains the getContentGroup(), therefore, the getContentTransform() does not influence the scroll offset.
      Returns:
      The Pane that is translated when scrolling.

    • getScrolledUnderlayGroup

      public Group getScrolledUnderlayGroup()
      Returns the scrolled underlay Group.
      Returns:
      The scrolled underlay Group.

    • getUnderlayGroup

      public Group getUnderlayGroup()
      Returns the underlay Group.
      Returns:
      The underlay Group.

    • getVerticalScrollBar

      public ScrollBar getVerticalScrollBar()
      Returns the vertical ScrollBar, or null if the vertical ScrollBar was not yet created.
      Returns:
      The vertical ScrollBar.

    • getVerticalScrollBarPolicy

      public ScrollPane.ScrollBarPolicy getVerticalScrollBarPolicy()
      Returns the ScrollPane.ScrollBarPolicy that is currently used to decide when to show a vertical scrollbar.
      Returns:
      The ScrollPane.ScrollBarPolicy that is currently used to decide when to show a vertical scrollbar.

    • getVerticalScrollOffset

      public double getVerticalScrollOffset()
      Returns the current vertical scroll offset.
      Returns:
      The current vertical scroll offset.

    • gridCellHeightProperty

      public IntegerProperty gridCellHeightProperty()
      Returns the grid cell height as a (writable) property.
      See Also:

    • gridCellWidthProperty

      public IntegerProperty gridCellWidthProperty()
      Returns the grid cell width as a (writable) property.
      See Also:

    • hideGrid

      protected void hideGrid()
      Disables the background grid.

    • horizontalScrollBarPolicyProperty

      public ObjectProperty<ScrollPane.ScrollBarPolicy> horizontalScrollBarPolicyProperty()
      Returns the ObjectProperty that controls the ScrollPane.ScrollBarPolicy that decides when to show a horizontal scrollbar.
      See Also:

    • horizontalScrollOffsetProperty

      public DoubleProperty horizontalScrollOffsetProperty()
      Returns the horizontal scroll offset as a property.
      See Also:

    • isClipContent

      public boolean isClipContent()
      Returns the value of the clipContentProperty().
      Returns:
      The value of the clipContentProperty().

    • isShowGrid

      public boolean isShowGrid()
      Returns the value of the showGridProperty().
      Returns:
      The value of the showGridProperty().

    • isZoomGrid

      public boolean isZoomGrid()
      Returns the value of the zoomGridProperty().
      Returns:
      The value of the zoomGridProperty().

    • lerp

      protected double lerp(double min, double max, double ratio)
      Linear interpolation between min and max at the given ratio. Returns the interpolated value in the interval [min;max].
      Parameters:
      min - The lower interval bound.
      max - The upper interval bound.
      ratio - A value in the interval [0;1].
      Returns:
      The interpolated value.

    • norm

      protected double norm(double min, double max, double value)
      Normalizes a given value which is in range [min;max] to range [0;1].
      Parameters:
      min - The lower bound of the range.
      max - The upper bound of the range.
      value - The value in the range.
      Returns:
      The normalized value (in range [0;1]).

    • registerFadeInOutTransitions

      protected void registerFadeInOutTransitions(Node node)
      Registers fade in/out transitions for the given Node. The transitions are used when the mouse enters/exits the node.
      Parameters:
      node - The Node to which fade in/out transitions are added upon mouse enter/exit.

    • registerUpdateScrollBarsOnBoundsChanges

      protected void registerUpdateScrollBarsOnBoundsChanges()
      Registers listeners on the bounds-in-local property of the getScrolledPane() and on the bounds-in-parent property of the getContentGroup() that will call updateScrollBars() when one of the bounds is changed.

    • registerUpdateScrollBarsOnPolicyChanges

      protected void registerUpdateScrollBarsOnPolicyChanges()
      Registers listeners on the horizontalScrollBarPolicyProperty() and on the verticalScrollBarPolicyProperty() that will call updateScrollBars() when one of the ScrollPane.ScrollBarPolicys changes.

    • registerUpdateScrollBarsOnSizeChanges

      protected void registerUpdateScrollBarsOnSizeChanges()
      Registers listeners on the Region.widthProperty() and on the Region.heightProperty() that will call updateScrollBars() when the size of this InfiniteCanvas changes.

    • repaintGrid

      protected void repaintGrid()
      Repaints the tile image that depends on the grid cell size only. The tile image is repeated when repainting the grid.

    • reveal

      public void reveal(Node child)
      Ensures that the specified child Node is visible to the user by scrolling to its position. The effect and style of the node are taken into consideration. After revealing a node, it will be fully visible if it fits within the current viewport bounds.

      When the child node's left side is left to the viewport, it will touch the left border of the viewport after revealing. When the child node's right side is right to the viewport, it will touch the right border of the viewport after revealing. When the child node's top side is above the viewport, it will touch the top border of the viewport after revealing. When the child node's bottom side is below the viewport, it will touch the bottom border of the viewport after revealing.

      The top and left sides have preference over the bottom and right sides, i.e. when the top side is aligned with the viewport, the bottom side will not be aligned, and when the left side is aligned with the viewport, the right side will not be aligned.

      Parameters:
      child - The child Node to reveal.

    • scrollableBoundsProperty

      public ReadOnlyObjectProperty<Bounds> scrollableBoundsProperty()
      Returns the bounds of the scrollable area in local coordinates of this InfiniteCanvas as a (read-only) property. The scrollable area corresponds to the visual bounds of the content group, which is expanded to cover at least the area of this InfiniteCanvas (i.e. the viewport) if necessary. It is thereby also the area that can be navigated via the scroll bars.
      See Also:

    • setClipContent

      public void setClipContent(boolean clipContent)
      Sets the value of the clipContentProperty() to the given value.
      Parameters:
      clipContent - The new value for the clipContentProperty().

    • setContentTransform

      public void setContentTransform(Affine tx)
      Sets the transformation matrix of the viewport transform to the values specified by the given Affine.
      Parameters:
      tx - The Affine determining the new viewport transform.

    • setGridCellHeight

      public void setGridCellHeight(int gridCellHeight)
      Assigns the given value to the gridCellHeightProperty().
      Parameters:
      gridCellHeight - The grid cell height that is assigned to the gridCellHeightProperty().

    • setGridCellWidth

      public void setGridCellWidth(int gridCellWidth)
      Assigns the given value to the gridCellWidthProperty().
      Parameters:
      gridCellWidth - The grid cell width that is assigned to the gridCellWidthProperty().

    • setHorizontalScrollBarPolicy

      public void setHorizontalScrollBarPolicy(ScrollPane.ScrollBarPolicy horizontalScrollBarPolicy)
      Sets the value of the horizontalScrollBarPolicyProperty() to the given ScrollPane.ScrollBarPolicy.
      Parameters:
      horizontalScrollBarPolicy - The new ScrollPane.ScrollBarPolicy for the horizontal scrollbar.

    • setHorizontalScrollOffset

      public void setHorizontalScrollOffset(double scrollOffsetX)
      Sets the horizontal scroll offset to the given value.
      Parameters:
      scrollOffsetX - The new horizontal scroll offset.

    • setShowGrid

      public void setShowGrid(boolean showGrid)
      Assigns the given value to the showGridProperty().
      Parameters:
      showGrid - The new value that is assigned to the showGridProperty().

    • setVerticalScrollBarPolicy

      public void setVerticalScrollBarPolicy(ScrollPane.ScrollBarPolicy verticalScrollBarPolicy)
      Sets the value of the verticalScrollBarPolicyProperty() to the given ScrollPane.ScrollBarPolicy.
      Parameters:
      verticalScrollBarPolicy - The new ScrollPane.ScrollBarPolicy for the vertical scrollbar.

    • setVerticalScrollOffset

      public void setVerticalScrollOffset(double scrollOffsetY)
      Sets the vertical scroll offset to the given value.
      Parameters:
      scrollOffsetY - The new vertical scroll offset.

    • setZoomGrid

      public void setZoomGrid(boolean zoomGrid)
      Assigns the given value to the showGridProperty().
      Parameters:
      zoomGrid - The new value that is assigned to the showGridProperty().

    • showGrid

      protected void showGrid()
      Enables the background grid.

    • showGridProperty

      public BooleanProperty showGridProperty()
      Returns the BooleanProperty that determines if a background grid is shown within this InfiniteCanvas.
      See Also:

    • unclipContent

      protected void unclipContent()
      Disables content clipping for this InfiniteCanvas.

    • unregisterUpdateScrollBarsOnBoundsChanges

      protected void unregisterUpdateScrollBarsOnBoundsChanges()
      Unregisters the listeners that were previously registered within registerUpdateScrollBarsOnBoundsChanges().

    • unzoomGrid

      protected void unzoomGrid()
      Disables zooming of the background grid.
      See Also:

    • updateGridTransform

      protected void updateGridTransform(Affine transform)
      This method is called when the grid transformation should be updated to match the given Affine. The grid transformation is
      Parameters:
      transform - The new transformation matrix for the grid canvas.

    • updateScrollBars

      protected void updateScrollBars()
      Updates the ScrollBars' visibilities, value ranges and value increments based on the content bounds and the scrollable bounds. The update is not done if any of the ScrollBars is currently in use.

    • verticalScrollBarPolicyProperty

      public ObjectProperty<ScrollPane.ScrollBarPolicy> verticalScrollBarPolicyProperty()
      Returns the ObjectProperty that controls the ScrollPane.ScrollBarPolicy that decides when to show a vertical scrollbar.
      See Also:

    • verticalScrollOffsetProperty

      public DoubleProperty verticalScrollOffsetProperty()
      Returns the vertical scroll offset as a property.
      See Also:

    • zoomGrid

      protected void zoomGrid()
      Enables zooming of the background grid when the contents are zoomed.

    • zoomGridProperty

      public BooleanProperty zoomGridProperty()
      Returns the BooleanProperty that determines if the background grid is zoomed when the contents are zoomed.
      See Also: