Package org.pepsoft.util.swing

Class TiledImageViewer

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
org.pepsoft.util.swing.TiledImageViewer
All Implemented Interfaces:
ComponentListener, HierarchyListener, MouseListener, MouseMotionListener, ImageObserver, MenuContainer, Serializable, Cloneable, EventListener, TileListener
public class TiledImageViewer extends JComponent implements TileListener, MouseListener, MouseMotionListener, ComponentListener, HierarchyListener, Cloneable
A generic visual component which can display one or more layers of large or even endless tile-based images, with support for scrolling and scaling the images.

The tiles are provided by tile providers. The tiles are requested asynchronously on multiple threads and are cached. This means that tile providers have to do no caching themselves and are free to calculate or generate each tile on request, even if that is relatively slow.

The tile providers are ordered on numbered layers. The numbering does not have to be continuous, and only one tile provider can be configured per layer. Lower numbered layers are rendered below higher numbered layers.

When zooming in, this viewer performs all the scaling itself. When zooming out, for tile providers which indicate that they support zooming, the scaling is delegated to the tile providers.

This class does not provide scrollbars, however it can be encapsulated in a TiledImageViewerContainer which will surround it with scrollbars, with support for the tile providers' extents.

See Also:

  • Field Details

    • viewX

      protected int viewX
      The currently displayed location in scaled coordinates.

    • viewY

      protected int viewY
      The currently displayed location in scaled coordinates.

    • previousX

      protected int previousX
      The previously displayed location in scaled coordinates. Used during mouse drag operations.

    • previousY

      protected int previousY
      The previously displayed location in scaled coordinates. Used during mouse drag operations.

    • markerX

      protected int markerX
      The image coordindates of the marker (if any) to paint as a red crosshair.

    • markerY

      protected int markerY
      The image coordindates of the marker (if any) to paint as a red crosshair.

    • xOffset

      protected int xOffset
      The offset to apply to the image so that the view coordinates are displayed in the centre of the view.

    • yOffset

      protected int yOffset
      The offset to apply to the image so that the view coordinates are displayed in the centre of the view.

    • TILE_SIZE

      public static final int TILE_SIZE
      See Also:

    • TILE_SIZE_BITS

      public static final int TILE_SIZE_BITS
      See Also:

    • TILE_SIZE_MASK

      public static final int TILE_SIZE_MASK
      See Also:

    • ADVANCED_SETTING_MAX_TILE_RENDER_THREADS

      public static final org.pepsoft.util.IntegerAttributeKey ADVANCED_SETTING_MAX_TILE_RENDER_THREADS

  • Constructor Details

    • TiledImageViewer

      public TiledImageViewer()
      Create a new tiled image viewer which allows panning by dragging with the left mouse button and which paints the central crosshair.

    • TiledImageViewer

      public TiledImageViewer(boolean leftClickDrags, boolean paintCentre)
      Create a new tiled image viewer.
      Parameters:
      leftClickDrags - Whether dragging with the left mouse button should pan the image.
      paintCentre - Whether the central crosshair indicating the current location should be painted.

    • TiledImageViewer

      public TiledImageViewer(boolean leftClickDrags, boolean paintCentre, int tileProviderZoomCutoff)
      Create a new tiled image viewer.
      Parameters:
      leftClickDrags - Whether dragging with the left mouse button should pan the image.
      paintCentre - Whether the central crosshair indicating the current location should be painted.
      tileProviderZoomCutoff - The zoom level below which zooming should be delegated to the tile providers that support it.

  • Method Details

    • getTileProviders

      public Collection<TileProvider> getTileProviders()
      Get an unmodifiable view of the currently configured list of tile providers.
      Returns:
      An unmodifyable view of the currently configured list of tile providers.

    • getTileProviderCount

      public int getTileProviderCount()
      Get the number of currently configured tile providers.
      Returns:
      The number of currently configured tile providers.

    • setTileProvider

      public void setTileProvider(TileProvider tileProvider)
      Set or replace a tile provider on layer 0 and reuse the existing provider's cached tile images as stale tile images for the new provider. Mainly meant as a convenience method for clients that will only ever use one tile provider at a time.
      Parameters:
      tileProvider - The tile provider to place at the specified layer.

    • setTileProvider

      public void setTileProvider(int layer, TileProvider tileProvider)
      Set or replace a tile provider on a specific layer and reuse the existing provider's cached tile images as stale tile images for the new provider.
      Parameters:
      layer - The layer at which to place the tile provider.
      tileProvider - The tile provider to place at the specified layer.

    • removeTileProvider

      public void removeTileProvider(int layer)
      Remove a tile provider.
      Parameters:
      layer - The layer on the tile provider to remove is placed.

    • removeAllTileProviders

      public void removeAllTileProviders()
      Remove all tile providers.

    • getViewX

      public int getViewX()
      Get the X coordinate in image coordinates of the centre of the view.
      Returns:
      The X coordinate in image coordinates of the centre of the view.

    • getViewY

      public int getViewY()
      Get the Y coordinate in image coordinates of the centre of the view.
      Returns:
      The Y coordinate in image coordinates of the centre of the view.

    • getExtent

      public Rectangle getExtent()
      Get the combined and zoom-corrected extent or main area of interest of all the tile providers, in component coordinates.
      Returns:
      The combined and zoom-corrected extent or main area of interest of all the tile providers, or null if there are no tile providers configured, or none of them indicate an extent.
      See Also:

    • getViewLocation

      public Point getViewLocation()
      Get the coordinate in image coordinates of the centre of the view.
      Returns:
      The coordinate in image coordinates of the centre of the view.

    • getZoom

      public int getZoom()
      Get the current zoom level in powers of two.
      Returns:
      The current zoom level as a power of two. The scale is 2zoom.

    • setZoom

      public void setZoom(int zoom)
      Set the zoom level in powers of two. 0 means "native size"; positive numbers zoom in (result in a larger scale); negative numbers zoom out (result in a smaller scale).
      Parameters:
      zoom - The new zoom level as a power of two. The scale will be 2zoom.

    • setZoom

      public void setZoom(int zoom, int locusX, int locusY)
      Set the zoom level in powers of two. 0 means "native size"; positive numbers zoom in (result in a larger scale); negative numbers zoom out (result in a smaller scale).
      Parameters:
      zoom - The new zoom level as a power of two. The scale will be 2zoom.

    • resetZoom

      public void resetZoom()

    • getMarkerCoords

      public Point getMarkerCoords()
      Get the coordinates in image coordinates of the marker (displayed as a red crosshair), if configured.
      Returns:
      The coordinates in image coordinates of the marker, or null if no marker is configured.

    • setMarkerCoords

      public void setMarkerCoords(Point markerCoords)
      Set the coordinates in image coordinates where a red crosshair marker should be displayed, if any.
      Parameters:
      markerCoords - The coordinates in image coordinates where a red crosshair marker should be displayed, or null if no marker should be displayed.

    • isPaintGrid

      public boolean isPaintGrid()
      Determine whether the grid is currently painted.
      Returns:
      true if the grid is currently painted.

    • setPaintGrid

      public void setPaintGrid(boolean paintGrid)
      Set whether the gid should be painted.
      Parameters:
      paintGrid - true if the grid should be painted.

    • getGridSize

      public int getGridSize()
      Get the current size in image coordinates of the grid.
      Returns:
      The current size in image coordinates of the grid.

    • setGridSize

      public void setGridSize(int gridSize)
      Set the size in image coordinates at which the grid should be painted.
      Parameters:
      gridSize - The size in image coordinates at which the grid should be painted.

    • moveTo

      public void moveTo(Point coords)
      Centre the view on a particular location in image coordinates.
      Parameters:
      coords - The coordinates in image coordinates of the location to centre.

    • moveTo

      public void moveTo(int x, int y)
      Centre the view on a particular location in image coordinates.
      Parameters:
      x - The X coordinate in image coordinates of the location to centre.
      y - The Y coordinate in image coordinates of the location to centre.

    • moveToMarker

      public void moveToMarker()
      Centre the view on the currently configured marker. Does nothing if no marker is configured.

    • moveToOrigin

      public void moveToOrigin()
      Centre the view on the image origin (coordinates 0,0).

    • moveBy

      public void moveBy(int dx, int dy)
      Move the view by a number of pixels. The actual movement in image coordinates may be different if the zoom level is not zero.
      Parameters:
      dx - The number of pixels to move the view right.
      dy - The number of pixels to move the view down.

    • refresh

      public void refresh()
      Immediately throws away and refreshes all tiles of all tile providers.

    • refresh

      public void refresh(boolean keepDirtyTiles)
      Refreshes all tiles of all tile providers.
      Parameters:
      keepDirtyTiles - Whether to keep displaying the old tiles while the new ones are being rendered.

    • refresh

      public void refresh(TileProvider tileProvider, int x, int y)
      Refresh a single tile for a single tile provider. If the tile is visible it will immediately be scheduled for background rendering. Otherwise it will be scheduled when it next becomes visible. If there is a fresh tile image in the cache that will be used as a stale tile image until it has been re-rendered.
      Parameters:
      tileProvider - The tile provider.
      x - The X coordinate of the tile in tiles relative to the image origin.
      y - The Y coordinate of the tile in tiles relative to the image origin.

    • refresh

      public void refresh(TileProvider tileProvider, Set<Point> tiles)
      Refresh a number of tiles for a single tile provider. Tiles that are currently visible will immediately be scheduled for background rendering. Otherwise they will be scheduled when they next become visible. Any fresh tile images in the cache will be used as stale tile images until the tiles are re-rendered.
      Parameters:
      tileProvider - The tile provider.
      tiles - A set of tile coordinates of the tiles to refresh, in tiles relative to the image origin.

    • reset

      @Deprecated public void reset()
      Deprecated.
      Reset the location to the origin, and the zoom level to -2.

    • worldToView

      public final Point worldToView(Point coords)
      Transform coordinates from image (world) coordinates to component (pixels relative to the top left corner) coordinates, taking the current zoom level into account.

    • worldToView

      public final Point worldToView(int x, int y)
      Transform coordinates from image (world) coordinates to component (pixels relative to the top left corner) coordinates, taking the current zoom level into account.

    • viewToWorld

      public final Point viewToWorld(Point coords)
      Transform coordinates from component (pixels relative to the top left corner) coordinates to image (world) coordinates, taking the current zoom level into account.

    • viewToWorld

      public final Point viewToWorld(int x, int y)
      Transform coordinates from component (pixels relative to the top left corner) coordinates to image (world) coordinates, taking the current zoom level into account. This version does not take tile-provider-specific offset into acount.

    • viewToWorld

      public final Point viewToWorld(Point coords, int effectiveZoom)
      Transform coordinates from component (pixels relative to the top left corner) coordinates to image (world) coordinates, using a specific zoom level. This version does not take per-tile-provider offsets into account.

    • viewToWorld

      public final Point viewToWorld(int x, int y, int effectiveZoom)
      Transform coordinates from component (pixels relative to the top left corner) coordinates to image (world) coordinates, using a specific zoom level. This version does not take per-tile-provider offsets into account.

    • worldToView

      public final Rectangle worldToView(Rectangle coords)
      Transform coordinates from image (world) coordinates to component (pixels relative to the top left corner) coordinates, taking the current zoom level into account.

    • worldToView

      public final Rectangle worldToView(int x, int y, int width, int height)
      Transform coordinates from image (world) coordinates to component (pixels relative to the top left corner) coordinates, taking the current zoom level into account.

    • worldToView

      public final Rectangle worldToView(Rectangle coords, int effectiveZoom)
      Transform coordinates from image (world) coordinates to component (pixels relative to the top left corner) coordinates, using a specific zoom level.

    • worldToView

      public final Rectangle worldToView(int x, int y, int width, int height, int effectiveZoom)
      Transform coordinates from image (world) coordinates to component (pixels relative to the top left corner) coordinates, using a specific zoom level. This version does not take tile-provider-specific offsets into account.

    • viewToWorld

      public final Rectangle viewToWorld(Rectangle coords)
      Transform coordinates from component (pixels relative to the top left corner) coordinates to image (world) coordinates, taking the current zoom level into account.

    • viewToWorld

      public final Rectangle viewToWorld(int x, int y, int width, int height)
      Transform coordinates from component (pixels relative to the top left corner) coordinates to image (world) coordinates, taking the current zoom level into account.

    • getViewListener

      public TiledImageViewer.ViewListener getViewListener()
      Get the view listener.
      Returns:
      The currently configured view listener, or null if none is configured.

    • setViewListener

      public void setViewListener(TiledImageViewer.ViewListener viewListener)
      Get the currently configured view listener, if any.
      Parameters:
      viewListener - The currently configured view listener, or null if there is none.

    • addOverlay

      public void addOverlay(String key, int x, Component componentToTrack, BufferedImage overlay)
      Add an overlay. An overlay is an image which is overlaid on the viewport, on the left or right edge of the view, vertically tracking some other component. The image may be partially transparent.
      Parameters:
      key - The unique key of the overlay to add.
      x - The horizontal distance from the left edge to paint the overlay, or if negative: the horizontal distance from the right edge.
      componentToTrack - The component of which the height should be tracked.
      overlay - The image to overlay on the view.

    • removeOverlay

      public void removeOverlay(String key)
      Remove a previously added overlay.
      Parameters:
      key - The unique key of the overlay to remove.

    • getGridColour

      public Color getGridColour()
      Get the colour in which the grid is painted.
      Returns:
      The colour in which the grid is painted.

    • setGridColour

      public void setGridColour(Color gridColour)
      Set the colour in which to paint the grid.
      Parameters:
      gridColour - The colour in which to paint the grid.

    • getBackgroundImage

      public BufferedImage getBackgroundImage()

    • setBackgroundImage

      public void setBackgroundImage(BufferedImage backgroundImage)

    • getBackgroundImageMode

      public TiledImageViewer.BackgroundImageMode getBackgroundImageMode()

    • setBackgroundImageMode

      public void setBackgroundImageMode(TiledImageViewer.BackgroundImageMode backgroundImageMode)

    • isInhibitUpdates

      public boolean isInhibitUpdates()

    • setInhibitUpdates

      public void setInhibitUpdates(boolean inhibitUpdates)

    • getLabelScale

      public int getLabelScale()

    • setLabelScale

      public void setLabelScale(int labelScale)

    • setTileProviderZoom

      public void setTileProviderZoom(TileProvider tileProvider, int zoom)

    • getVisibleArea

      public Rectangle getVisibleArea()
      Get the currently visible area in world coordinates.
      Returns:
      The currently visible area in world coordinates.

    • clone

      public TiledImageViewer clone()
      Create clone of this tiled image viewer with a copy of the current tile providers and tile provider caches, so that it can immediately display the same content, but then behave independently with regard to zooming and panning.
      Overrides:
      clone in class Object
      Returns:
      A clone of this tiled image viewer with the same tile providers and a copy of the current contents of the caches.

    • isTileVisible

      protected final boolean isTileVisible(int x, int y, int effectiveZoom)
      Determine whether a tile is currently visible in the viewport.
      Parameters:
      x - The X coordinate of the tile to check for visibility.
      y - The Y coordinate of the tile to check for visibility.
      effectiveZoom - The zoom level to take into account.
      Returns:
      true if any part of the specified tile intersects the viewport.

    • getTileBounds

      protected final Rectangle getTileBounds(int x, int y)
      Get the bounds of a tile in component coordinates, taking the current zoom level into account.
      Parameters:
      x - The X coordinate of the tile for which to determine the bounds.
      y - The X coordinate of the tile for which to determine the bounds.
      Returns:
      The area in component coordinates taken up by the specified tile.

    • getTileBounds

      protected final Rectangle getTileBounds(int x, int y, int effectiveZoom)
      Get the bounds of a tile in component coordinates, taking a specific zoom level into account. This version does not take per-tile-provider offsets into account.
      Parameters:
      x - The X coordinate of the tile for which to determine the bounds.
      y - The X coordinate of the tile for which to determine the bounds.
      effectiveZoom - The zoom level to take into account.
      Returns:
      The area in component coordinates taken up by the specified tile.

    • getTileBounds

      protected final Rectangle getTileBounds(int x, int y, int width, int height, int effectiveZoom)
      Get the bounds of a rectangular area of tiles in component coordinates, taking a specific zoom level into account. This version does not take tile-provider-specific offsets into account.
      Parameters:
      x - The X coordinate of the top left tile of the area for which to determine the bounds.
      y - The X coordinate of the top left tile of the area for which to determine the bounds.
      width - The width in tiles of the area for which to determine the bounds.
      height - The height in tiles of the area for which to determine the bounds.
      effectiveZoom - The zoom level to take into account.
      Returns:
      The area in component coordinates taken up by the specified rectangle of tiles.

    • transformGraphics

      protected final float transformGraphics(Graphics2D g2)
      Apply translation and scaling to a graphics canvas according to the current location and zoom settings such that it can be painted using image coordinates.
      Parameters:
      g2 - The graphics canvas to which to apply the transforms.
      Returns:
      The scaling factor to apply to image coordinates to account for the zoom level.

    • paintComponent

      protected void paintComponent(Graphics g)
      Overrides:
      paintComponent in class JComponent

    • componentResized

      public void componentResized(ComponentEvent e)
      Specified by:
      componentResized in interface ComponentListener

    • componentShown

      public void componentShown(ComponentEvent e)
      Specified by:
      componentShown in interface ComponentListener

    • componentMoved

      public void componentMoved(ComponentEvent e)
      Specified by:
      componentMoved in interface ComponentListener

    • componentHidden

      public void componentHidden(ComponentEvent e)
      Specified by:
      componentHidden in interface ComponentListener

    • tileChanged

      public void tileChanged(TileProvider source, int x, int y)
      Description copied from interface: TileListener
      Invoked when the contents of a tile have changed and the tile should be retrieved again.
      Specified by:
      tileChanged in interface TileListener
      Parameters:
      source - The tile provider from which the changed tile should be retrieved.
      x - The X coordinate (in tiles) of the changed tile.
      y - The Y coordinate (in tiles) of the changed tile.

    • tilesChanged

      public void tilesChanged(TileProvider source, Set<Point> tiles)
      Description copied from interface: TileListener
      Invoked when the contents of one or more tiles have changed and the tile(s) should be retrieved again.
      Specified by:
      tilesChanged in interface TileListener
      Parameters:
      source - The tile provider from which the changed tile(s) should be retrieved.
      tiles - The set of coordinates of the changed tile(s).

    • mousePressed

      public void mousePressed(MouseEvent e)
      Specified by:
      mousePressed in interface MouseListener

    • mouseReleased

      public void mouseReleased(MouseEvent e)
      Specified by:
      mouseReleased in interface MouseListener

    • mouseClicked

      public void mouseClicked(MouseEvent e)
      Specified by:
      mouseClicked in interface MouseListener

    • mouseEntered

      public void mouseEntered(MouseEvent e)
      Specified by:
      mouseEntered in interface MouseListener

    • mouseExited

      public void mouseExited(MouseEvent e)
      Specified by:
      mouseExited in interface MouseListener

    • mouseDragged

      public void mouseDragged(MouseEvent e)
      Specified by:
      mouseDragged in interface MouseMotionListener

    • mouseMoved

      public void mouseMoved(MouseEvent e)
      Specified by:
      mouseMoved in interface MouseMotionListener

    • hierarchyChanged

      public void hierarchyChanged(HierarchyEvent event)
      Specified by:
      hierarchyChanged in interface HierarchyListener