de.cismet.tools.gui

Class NavigableImagePanel

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JPanel

de.cismet.tools.gui.NavigableImagePanel

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible

public class NavigableImagePanel
extends JPanel

NavigableImagePanel is a lightweight container displaying an image that can be zoomed in and out and panned with ease and simplicity, using an adaptive rendering for high quality display and satisfactory performance.

Image

An image is loaded either via a constructor:

   NavigableImagePanel panel = new NavigableImagePanel(image);
 

or using a setter:

   NavigableImagePanel panel = new NavigableImagePanel();
   panel.setImage(image);
 

When an image is set, it is initially painted centered in the component, at the largest possible size, fully visible, with its aspect ratio is preserved. This is defined as 100% of the image size and its corresponding zoom level is 1.0.

Zooming

Zooming can be controlled interactively, using either the mouse scroll wheel (default) or the mouse two buttons, or programmatically, allowing the programmer to implement other custom zooming methods. If the mouse does not have a scroll wheel, set the zooming device to mouse buttons:

   panel.setZoomDevice(ZoomDevice.MOUSE_BUTTON);
 

The left mouse button works as a toggle switch between zooming in and zooming out modes, and the right button zooms an image by one increment (default is 20%). You can change the zoom increment value by:

   panel.setZoomIncrement(newZoomIncrement);
 

If you intend to provide programmatic zoom control, set the zoom device to none to disable both the mouse wheel and buttons for zooming purposes:

   panel.setZoomDevice(ZoomDevice.NONE);
 

and use setZoom() to change the zoom level.

Zooming is always around the point the mouse pointer is currently at, so that this point (called a zooming center) remains stationary ensuring that the area of an image we are zooming into does not disappear off the screen. The zooming center stays at the same location on the screen and all other points move radially away from it (when zooming in), or towards it (when zooming out). For programmatically controlled zooming the zooming center is either specified when setZoom() is called:

   panel.setZoom(newZoomLevel, newZoomingCenter);
 

or assumed to be the point of an image which is the closest to the center of the panel, if no zooming center is specified:

   panel.setZoom(newZoomLevel);
 

There are no lower or upper zoom level limits.

Navigation

NavigableImagePanel does not use scroll bars for navigation, but relies on a navigation image located in the upper left corner of the panel. The navigation image is a small replica of the image displayed in the panel. When you click on any point of the navigation image that part of the image is displayed in the panel, centered. The navigation image can also be zoomed in the same way as the main image.

In order to adjust the position of an image in the panel, it can be dragged with the mouse, using the left button.

For programmatic image navigation, disable the navigation image:

   panel.setNavigationImageEnabled(false)
 

and use getImageOrigin() and setImageOrigin() to move the image around the panel.

Rendering

NavigableImagePanel uses the Nearest Neighbor interpolation for image rendering (default in Java). When the scaled image becomes larger than the original image, the Bilinear interpolation is applied, but only to the part of the image which is displayed in the panel. This interpolation change threshold can be controlled by adjusting the value of HIGH_QUALITY_RENDERING_SCALE_THRESHOLD.

Version:

$Revision$, $Date$

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NavigableImagePanel.ZoomDevice Defines zoom devices.

Nested classes/interfaces inherited from class javax.swing.JPanel

JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static String	IMAGE_CHANGED_PROPERTY .
static String	ZOOM_INCREMENT_CHANGED_PROPERTY .
static String	ZOOM_LEVEL_CHANGED_PROPERTY .

Fields inherited from class javax.swing.JComponent

listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
NavigableImagePanel() Creates a new navigable image panel with no default image and the mouse scroll wheel as the zooming device.
NavigableImagePanel(BufferedImage image) Creates a new navigable image panel with the specified image and the mouse scroll wheel as the zooming device.

Method Summary

Modifier and Type	Method and Description
Point	getImageOrigin() Gets the image origin.
double	getZoom() Gets the current zoom level.
NavigableImagePanel.ZoomDevice	getZoomDevice() Gets the current zoom device.
double	getZoomIncrement() Gets the current zoom increment.
boolean	isHighQualityRenderingEnabled() Indicates whether the high quality rendering feature is enabled.
boolean	isNavigationImageEnabled() Indicates whether navigation image is enabled.
static boolean	isStandardRGBImage(BufferedImage bImage) Tests whether an image uses the standard RGB color space.
static void	main(String[] args) DOCUMENT ME!
protected void	paintComponent(Graphics g) Paints the panel and its image at the current zoom level, location, and interpolation method dependent on the image scale.
void	setHighQualityRenderingEnabled(boolean enabled) Enables/disables high quality rendering.
void	setImage(BufferedImage image) Sets an image for display in the panel.
void	setImageOrigin(int x, int y) Sets the image origin.
void	setImageOrigin(Point newOrigin) Sets the image origin.
void	setNavigationImageEnabled(boolean enabled) Enables/disables navigation with the navigation image.
void	setZoom(double newZoom) Sets the zoom level used to display the image.
void	setZoom(double newZoom, Point zoomingCenter) Sets the zoom level used to display the image, and the zooming center, around which zooming is done.
void	setZoomDevice(NavigableImagePanel.ZoomDevice newZoomDevice) Sets a new zoom device.
void	setZoomIncrement(double newZoomIncrement) Sets a new zoom increment value.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

ZOOM_LEVEL_CHANGED_PROPERTY

public static final String ZOOM_LEVEL_CHANGED_PROPERTY

.

Identifies a change to the zoom level.

See Also:

Constant Field Values

ZOOM_INCREMENT_CHANGED_PROPERTY

public static final String ZOOM_INCREMENT_CHANGED_PROPERTY

.

Identifies a change to the zoom increment.

See Also:

Constant Field Values

IMAGE_CHANGED_PROPERTY

public static final String IMAGE_CHANGED_PROPERTY

.

Identifies that the image in the panel has changed.

See Also:

Constant Field Values

Constructor Detail

NavigableImagePanel

public NavigableImagePanel()

Creates a new navigable image panel with no default image and the mouse scroll wheel as the zooming device.

NavigableImagePanel

public NavigableImagePanel(BufferedImage image)
                    throws IOException

Creates a new navigable image panel with the specified image and the mouse scroll wheel as the zooming device.

Parameters:

image - DOCUMENT ME!

Throws:

IOException - DOCUMENT ME!

Method Detail

setZoomDevice

public void setZoomDevice(NavigableImagePanel.ZoomDevice newZoomDevice)

Sets a new zoom device.

Parameters:

newZoomDevice - specifies the type of a new zoom device.

getZoomDevice

public NavigableImagePanel.ZoomDevice getZoomDevice()

Gets the current zoom device.

Returns:

DOCUMENT ME!

setImage

public void setImage(BufferedImage image)

Sets an image for display in the panel.

Parameters:

image - an image to be set in the panel

isStandardRGBImage

public static boolean isStandardRGBImage(BufferedImage bImage)

Tests whether an image uses the standard RGB color space.

Parameters:

bImage - DOCUMENT ME!

Returns:

DOCUMENT ME!

isHighQualityRenderingEnabled

public boolean isHighQualityRenderingEnabled()

Indicates whether the high quality rendering feature is enabled.

Returns:

true if high quality rendering is enabled, false otherwise.

setHighQualityRenderingEnabled

public void setHighQualityRenderingEnabled(boolean enabled)

Enables/disables high quality rendering.

Parameters:

enabled - enables/disables high quality rendering

isNavigationImageEnabled

public boolean isNavigationImageEnabled()

Indicates whether navigation image is enabled.

Returns:

true when navigation image is enabled, false otherwise.

setNavigationImageEnabled

public void setNavigationImageEnabled(boolean enabled)

Enables/disables navigation with the navigation image.

Navigation image should be disabled when custom, programmatic navigation is implemented.

Parameters:

enabled - true when navigation image is enabled, false otherwise.

getZoom

public double getZoom()

Gets the current zoom level.

Returns:

the current zoom level

setZoom

public void setZoom(double newZoom)

Sets the zoom level used to display the image.

This method is used in programmatic zooming. The zooming center is the point of the image closest to the center of the panel. After a new zoom level is set the image is repainted.

Parameters:

newZoom - the zoom level used to display this panel's image.

setZoom

public void setZoom(double newZoom,
                    Point zoomingCenter)

Sets the zoom level used to display the image, and the zooming center, around which zooming is done.

This method is used in programmatic zooming. After a new zoom level is set the image is repainted.

Parameters:

newZoom - the zoom level used to display this panel's image.

zoomingCenter - DOCUMENT ME!

getZoomIncrement

public double getZoomIncrement()

Gets the current zoom increment.

Returns:

the current zoom increment

setZoomIncrement

public void setZoomIncrement(double newZoomIncrement)

Sets a new zoom increment value.

Parameters:

newZoomIncrement - new zoom increment value

getImageOrigin

public Point getImageOrigin()

Gets the image origin.

Image origin is defined as the upper, left corner of the image in the panel's coordinate system.

Returns:

the point of the upper, left corner of the image in the panel's coordinates system.

setImageOrigin

public void setImageOrigin(int x,
                           int y)

Sets the image origin.

Image origin is defined as the upper, left corner of the image in the panel's coordinate system. After a new origin is set, the image is repainted. This method is used for programmatic image navigation.

Parameters:

x - the x coordinate of the new image origin

y - the y coordinate of the new image origin

setImageOrigin

public void setImageOrigin(Point newOrigin)

Sets the image origin.

Image origin is defined as the upper, left corner of the image in the panel's coordinate system. After a new origin is set, the image is repainted. This method is used for programmatic image navigation.

Parameters:

newOrigin - the value of a new image origin

paintComponent

protected void paintComponent(Graphics g)

Paints the panel and its image at the current zoom level, location, and interpolation method dependent on the image scale.

Overrides:

paintComponent in class JComponent

Parameters:

g - the Graphics context for painting

main

public static void main(String[] args)

DOCUMENT ME!

Parameters:

args - DOCUMENT ME!