Package ca.corbett.extras.image

Class ImagePanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
ca.corbett.extras.image.ImagePanel
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, ImageObserver, MenuContainer, Serializable, EventListener, Accessible
public class ImagePanel extends JPanel implements MouseListener, MouseWheelListener, MouseMotionListener
A custom JPanel extension that can display an image in configurable ways, with optional handling of mouse events to allow zooming and scrolling. Defaults are provided for all configuration options. Alternatively, you can create an ImagePanelConfig instance and override some or all of those defaults.
Since:
2012-09-22 (originally for StegPng, later generified for ca.corbett.util.ui)
Author:
scorbo2
See Also:

  • Field Details

    • extraAttributes

      protected final Map<String,Object> extraAttributes
      An optional map of extra, caller-supplied attributes. *

    • dBuffer

      protected BufferedImage dBuffer
      A handle on the image which will be displayed in this panel. This is set to null and ignored if an ImageIcon is set instead.

    • imageIcon

      protected ImageIcon imageIcon
      A handle on the ImageIcon which will be displayed in this panel. This is set to null and ignored if a BufferedImage is set instead.

    • imageIconLabel

      protected JLabel imageIconLabel
      A wrapper label for the imageIcon, if set. If a BufferedImage is set instead of an ImageIcon, then this property is ignored.

    • lastRenderedImageWidth

      protected int lastRenderedImageWidth
      The last rendered width of our image. If the image is scaled or if the panel is resized, the image may need to be re-rendered at a different size.

    • lastRenderedImageHeight

      protected int lastRenderedImageHeight
      The last rendered height of our image.If the image is scaled or if the panel is resized, the image may need to be re-rendered at a different size.

    • properties

      protected ImagePanelConfig properties
      A handle on our ImagePanelConfig configuration object. *

    • originalProperties

      protected ImagePanelConfig originalProperties
      A handle on the original ImagePanelConfig (needed because we'll modify these). *

    • zoomFactor

      protected double zoomFactor
      Stores the current zoomFactor (1 for no zoom, higher numbers = more zoom). *

    • zoomCenter

      protected Point zoomCenter
      A Point which represents the co-ordinates around which zoom operations will happen. *

    • mouseDragPoint

      protected Point mouseDragPoint
      Used internally for mouse dragging operations. *

    • mouseDragDelta

      protected Point mouseDragDelta
      Used internally for mouse dragging operations. *

    • imageX

      protected int imageX
      Used internally for image placement. *

    • imageY

      protected int imageY
      Used internally for image placement. *

    • popupMenu

      protected JPopupMenu popupMenu
      An optional popup menu for this ImagePanel. *

  • Constructor Details

    • ImagePanel

      public ImagePanel()
      Creates a new ImagePanel with a default ImagePanelConfig and no image.

    • ImagePanel

      public ImagePanel(BufferedImage image)
      Creates an ImagePanel with the given image and with a default ImagePanelConfig.
      Parameters:
      image - The image to display in this panel. Can be null.

    • ImagePanel

      public ImagePanel(ImagePanelConfig ipc)
      Creates an empty ImagePanel (no image) with the given ImagePanelConfig.
      Parameters:
      ipc - The ImagePanelConfig specifying our panel configuration.

    • ImagePanel

      public ImagePanel(ImageIcon icon)
      Creates an ImagePanel with the given ImageIcon and a default ImagePanelConfig.
      Parameters:
      icon - The ImageIcon to display in this panel. Can be null.

    • ImagePanel

      public ImagePanel(BufferedImage image, ImagePanelConfig props)
      Creates an ImagePanel with the given image and the given ImagePanelConfig.
      Parameters:
      image - The image to display in this panel. Can be null.
      props - The ImagePanelConfig specifying our panel configuration.

    • ImagePanel

      public ImagePanel(ImageIcon icon, ImagePanelConfig props)
      Creates an ImagePanel with the given ImageIcon and ImagePanelConfig.
      Parameters:
      icon - The ImageIcon to display in this panel. Can be null.
      props - The ImagePanelConfig specifying our panel configuration.

    • ImagePanel

      protected ImagePanel(BufferedImage image, ImageIcon icon, ImagePanelConfig props)
      Invoked internally to set up a new ImagePanel with EITHER the given BufferedImage or the given ImageIcon - one of those two must be null, as both can't be displayed.
      Parameters:
      image - A BufferedImage to display. Must be null if icon is set.
      icon - An ImageIcon to display. Must be null if image is set.
      props - The ImagePanelConfig to use. Can be null for default configuration.

  • Method Details

    • applyProperties

      public void applyProperties(ImagePanelConfig props)
      Applies the configuration options in the given ImagePanelConfig instance to this panel. Changes take effect immediately and do not require a manual call to repaint(). If the supplied ImagePanelConfig is null, a default properties instance will be used instead.
      Parameters:
      props - The ImagePanelConfig instance containing our new configuration.

    • setExtraAttribute

      public void setExtraAttribute(String name, Object value)
      Sets an optional "extra attribute", which can be anything caller-defined. Can be retrieved later by getExtraAttribute.
      Parameters:
      name - The name of this extra attribute. Case insensitive.
      value - The value of this extra attribute. Accepted as-is and not modified by this class.

    • getExtraAttribute

      public Object getExtraAttribute(String name)
      Returns the value of the named extra attribute, if it exists.
      Parameters:
      name - The name of the extra attribute. Case insensitive.
      Returns:
      The named extra attribute, or null if no such attribute is set.

    • clearExtraAttributes

      public void clearExtraAttributes()
      Clears the list of extra attributes.

    • getImageWidth

      public int getImageWidth()
      Returns the width of the current BufferedImage or the current ImageIcon, depending on which one is set. If neither is set, returns 0.
      Returns:
      The width of the current image, or 0 if no image is shown.

    • getImageHeight

      public int getImageHeight()
      Returns the height of the current BufferedImage or the current ImageIcon, depending on which one is set. If neither is set, returns 0.
      Returns:
      The height of the current image, or 0 if no image is shown.

    • setZoomFactor

      public void setZoomFactor(double newFactor)
      Sets the factor for zooming - this is scaled around 1.0 being synonymous with "no zoom". A value of 0.5 means half normal size, a value of 2.0 means double normal size, and so on. Setting any value here will automatically disable autoBestFit. To re-enable best bit, you can either re-apply the ImagePanelConfig or simply call zoomBestFit in this class.
      Parameters:
      newFactor - The new zoom factor.

    • getZoomFactor

      public double getZoomFactor()
      Returns the current zoom factor.
      Returns:
      The current zoom factor. See setZoomFactor for more information.

    • zoomIn

      public void zoomIn(Point point)
      Zooms in around the given point. Invoking this will automatically disable autoBestFit. To re-enable it, try zoomBestFit() or re-apply your ImagePanelConfig.
      Parameters:
      point - The Point around which to zoom. To zoom to the center, use zoomIn() instead.

    • zoomIn

      public void zoomIn()
      Zooms in towards the center of the image. Invoking this will automatically disable autoBestFit. To re-enable best fit, try zoomBestFit() or re-apply your ImagePanelConfig().

    • zoomOut

      public void zoomOut(Point point)
      Zooms out from the given point. Invoking this will automatically disable autoBestFit. To re-enable best fit, try zoomBestFit() or re-apply your ImagePanelConfig().
      Parameters:
      point - The point around which to zoom out. To zoom out from center, try zoomOut instead.

    • zoomOut

      public void zoomOut()
      Zooms out from the center of the image. Invoking this will automatically disable autoBestFit. To re-enable best fit, try zoomBestFit() or re-apply your ImagePanelConfig().

    • zoomBestFit

      public void zoomBestFit()
      Enables (or re-enables) autoBestFit, and renders the image to fit the panel.

    • stretchImage

      public void stretchImage()
      Enabled (or re-enabled) STRETCH DisplayMode, and distorts the image to fit the panel.

    • setZoomCenter

      public void setZoomCenter(Point point)
      Sets the point around which to base zoom operations. Only used if displayMode is CUSTOM. By default, the zoom center is the center of the image.
      Parameters:
      point - The new point within the image around which to base zoom in/zoom out operations.

    • getZoomCenter

      public Point getZoomCenter()
      Returns the current zoom point, if set.
      Returns:
      The current point around which to base zoom operations, or null if not set.

    • resetZoomCenter

      public void resetZoomCenter()
      Resets the zoom center to be the center of the image.

    • getTranslatedPoint

      public Point getTranslatedPoint(Point p)
      Takes a co-ordinate inside this panel and translates it into a co-ordinate inside the image, taking current zoom factor and location into account.
      Parameters:
      p - The point inside this panel
      Returns:
      A point inside the image that corresponds to the input point.

    • setImage

      public void setImage(BufferedImage image)
      Replaces the current image with the given one. If autoBestFit is enabled, the image will be scaled up or down as needed. Else it is simply shown at scale factor 1.
      Parameters:
      image - The new image to be displayed, or null.

    • setImageIcon

      public void setImageIcon(ImageIcon icon)

    • getImage

      public BufferedImage getImage()
      Returns the current BufferedImage, if one is set.
      Returns:
      The BufferedImage currently being displayed in this panel, if there is one.

    • getImageIcon

      public ImageIcon getImageIcon()
      Returns the current ImageIcon, if one is set.
      Returns:
      The ImageIcon being displayed in this panel, if there is one.

    • paintComponent

      public void paintComponent(Graphics g)
      Overridden from JComponent, this method renders the image using current options.
      Overrides:
      paintComponent in class JComponent
      Parameters:
      g - The Graphics object to use for rendering.

    • setRenderingQuality

      protected void setRenderingQuality(Graphics2D graphics2D)
      Internal method to set rendering quality hints on a given Graphics2D instance based on the current ImagePanelConfig.getRenderingQuality() value.
      Parameters:
      graphics2D - The Graphics2D object to update.

    • translatePoint

      protected Point translatePoint(Point p)
      Takes a co-ordinate inside this panel and translates it into a co-ordinate inside the image, taking current zoom factor and location into account.
      Parameters:
      p - The point inside this panel
      Returns:
      A point inside the image that corresponds to the input point.

    • mouseClicked

      public void mouseClicked(MouseEvent e)
      Invoked automatically when the user clicks on the panel. If click to zoom is enabled in our properties, you can left click to zoom in and right click to zoom out. Otherwise this does nothing.
      Specified by:
      mouseClicked in interface MouseListener
      Parameters:
      e - The MouseEvent in question.

    • mousePressed

      public void mousePressed(MouseEvent e)
      Invoked automatically when the user presses a mouse button over the panel. If mouse dragging is enabled, you can scroll the image by clicking and dragging it (only if the image is larger than the panel or is zoomed in to that extent). If mouse dragging is disabled, or if the image is smaller than the panel, this does nothing.
      Specified by:
      mousePressed in interface MouseListener
      Parameters:
      e - The MouseEvent in question.

    • mouseReleased

      public void mouseReleased(MouseEvent e)
      Ignored; does nothing.
      Specified by:
      mouseReleased in interface MouseListener
      Parameters:
      e - Ignored.

    • mouseEntered

      public void mouseEntered(MouseEvent e)
      Ignored; does nothing.
      Specified by:
      mouseEntered in interface MouseListener
      Parameters:
      e - Ignored.

    • mouseExited

      public void mouseExited(MouseEvent e)
      Ignored; does nothing.
      Specified by:
      mouseExited in interface MouseListener
      Parameters:
      e - Ignored.

    • mouseWheelMoved

      public void mouseWheelMoved(MouseWheelEvent e)
      Invoked automatically when the user mouse wheels while over this panel. If zoom on mouse wheel is enabled, you can zoom in by wheeling up and zoom out by wheeling down. If zoom on mouse wheel is disabled, this does nothing.
      Specified by:
      mouseWheelMoved in interface MouseWheelListener
      Parameters:
      e - The MouseEvent in question.

    • mouseDragged

      public void mouseDragged(MouseEvent e)
      Invoked automatically when the user drags the mouse on this panel. If mouse dragging is enabled, you can click and drag to scroll the image around in cases where the image is larger than the panel (or is zoomed in to that extent). If mouse dragging is disabled, or if the image is smaller than the panel, this does nothing.
      Specified by:
      mouseDragged in interface MouseMotionListener
      Parameters:
      e - The MouseEvent in question.

    • mouseMoved

      public void mouseMoved(MouseEvent e)
      Ignored; does nothing.
      Specified by:
      mouseMoved in interface MouseMotionListener
      Parameters:
      e - Ignored.

    • setPopupMenu

      public void setPopupMenu(JPopupMenu menu)
      Associates the given JPopupMenu with this ImagePanel instance. The popup menu will only pop if the current image is not null.
      Parameters:
      menu - The new JPopupMenu to use. Can be null to disable popup menu.

    • addMouseListener

      public void addMouseListener(MouseListener listener)
      Overrides:
      addMouseListener in class Component

    • removeMouseListener

      public void removeMouseListener(MouseListener listener)
      Overrides:
      removeMouseListener in class Component