|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
ObjectComponent
Container
JComponent
ZoomPane
public abstract class ZoomPane
Base class for widget with a zoomable content. User can perform zooms using keyboard, menu
or mouse. ZoomPane
is an abstract class. Subclass must override at least two methods:
getArea()
, which must return a bounding box for the content to paint. This
area can be expressed in arbitrary units. For example, an object wanting to display a
geographic map with a content ranging from 10° to 15°E and 40° to 45°N should override
this method as follows:
public Rectangle2D getArea() { return new Rectangle2D.Double(10, 40, 5, 5); }
paintComponent(Graphics2D)
, which must paint the widget
content. Implementation must invoke
graphics.transform({link #zoom})
somewhere in its code in order to perform the zoom. Note that, by default, the
zoom is initialized in such a way that the y axis points upwards,
like the convention in geometry. This is as opposed to the default Java2D axis orientation,
where the y axis points downwards. If the implementation wants to paint text,
it should do this with the default transform. Example:
protected void paintComponent(final Graphics2D graphics) {
graphics.clip({link #getZoomableBounds getZoomableBounds}(null));
final AffineTransform textTr = graphics.getTransform();
graphics.transform({link #zoom});
// Paint the widget here, using logical coordinates. The
// coordinate system is the same as getArea()
's one.
graphics.setTransform(textTr);
// Paint any text here, in pixel coordinates.
}
Subclass can also override reset()
, which sets up the initial zoom. The
default implementation sets up the initial zoom in such a way that the following relations are
approximately held:
Logical coordinates provided bygetPreferredArea()
, after an affine transform described byzoom
, match pixel coordinates provided bygetZoomableBounds(Rectangle)
.
The "preferred area" is initially the same as getArea()
. The user can specify a
different preferred area with setPreferredArea(java.awt.geom.Rectangle2D)
. The user can also reduce zoomable
bounds by inserting an empty border around the widget, e.g.:
setBorder(BorderFactory.createEmptyBorder(top, left, bottom, right));
transform(java.awt.geom.AffineTransform)
. Derived classes can redefine this method if they want to take particular
actions during zooms, for example, modifying the minimum and maximum of a graph's axes.
The table below shows the keyboard presses assigned to each zoom:
Key | Purpose | Action name |
---|---|---|
![]() | Scroll up | "Up" |
![]() | Scroll down | "Down" |
![]() | Scroll left | "Left" |
![]() | Scroll right | "Right" |
![]() | Zoom in | "ZoomIn" |
![]() | Zoom out | "ZoomOut" |
![]() | Zoom | "Zoom" |
![]() | Default zoom | "Reset" |
Ctrl+![]() | Anti-clockwise rotation | "RotateLeft" |
Ctrl+![]() | Clockwise rotation | "RotateRight" |
getActionMap()
.get("ZoomIn")
.
Note: JScrollPane
objects are not suitable for adding scrollbars
to a ZoomPane
object. Instead, use createScrollPane()
. Once again, all
movements performed by the user through the scrollbars will be translated by calls to
transform(java.awt.geom.AffineTransform)
.
Nested Class Summary |
---|
Nested classes/interfaces inherited from class JComponent |
---|
JComponent.AccessibleJComponent |
Nested classes/interfaces inherited from class Container |
---|
Container.AccessibleAWTContainer |
Nested classes/interfaces inherited from class Component |
---|
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy |
Field Summary | |
---|---|
static int |
DEFAULT_ZOOM
Constant indicating default zoom close to the maximum permitted zoom. |
static int |
RESET
Constant indicating the resetting of scale, rotation and translation to a default value which makes the whole graphic appear in a window. |
static int |
ROTATE
Constant indicating a rotation. |
static int |
SCALE_X
Constant indicating the scale changes on the x axis. |
static int |
SCALE_Y
Constant indicating the scale changes on the y axis. |
static int |
TRANSLATE_X
Constant indicating the translations on the x axis. |
static int |
TRANSLATE_Y
Constant indicating the translations on the y axis. |
static int |
UNIFORM_SCALE
Constant indicating the scale changes on the x and y axes, with the added condition that these changes must be uniform. |
protected AffineTransform |
zoom
Affine transform containing zoom factors, translations and rotations. |
Fields inherited from class JComponent |
---|
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW |
Fields inherited from class Component |
---|
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT |
Fields inherited from interface ImageObserver |
---|
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH |
Constructor Summary | |
---|---|
ZoomPane(int type)
Construct a ZoomPane . |
Method Summary | |
---|---|
void |
addMouseListener(MouseListener listener)
Adds an object to the list of objects interested in being notified about mouse events. |
void |
addZoomChangeListener(ZoomChangeListener listener)
Adds an object to the list of objects interested in being notified about zoom changes. |
void |
buildNavigationMenu(JMenu menu)
Adds navigation options to the specified menu. |
void |
correctApparentPixelPosition(Point2D point)
Corrects a pixel's coordinates for removing the effect of the magnifying glass. |
JComponent |
createScrollPane()
Returns an object which displays this ZoomPane with the scrollbars. |
protected void |
fireZoomChanged(AffineTransform change)
Signals that a zoom change has taken place. |
abstract Rectangle2D |
getArea()
Returns a bounding box that contains the logical coordinates of all data that may be displayed in this ZoomPane . |
protected Dimension |
getDefaultSize()
Returns the default size for this component. |
Insets |
getInsets()
Returns the Insets of this component. |
Insets |
getInsets(Insets insets)
Returns the Insets of this component. |
Paint |
getMagnifierBorder()
Returns the color of the magnifying glass's border. |
Paint |
getMagnifierGlass()
Returns the color with which to tint magnifying glass. |
protected JPopupMenu |
getMagnifierMenu(MouseEvent event)
Method called automatically when the user clicks on the right mouse button inside the magnifying glass. |
protected Shape |
getMouseSelectionShape(Point2D point)
Returns the geometric shape to be used to delimitate an area. |
protected JPopupMenu |
getPopupMenu(MouseEvent event)
Method called automatically when the user clicks on the right mouse button. |
Rectangle2D |
getPreferredArea()
Returns the logical coordinates of the region that we want to see displayed the first time that ZoomPane appears on the screen. |
protected Dimension2D |
getPreferredPixelSize()
Returns the preferred pixel size for a close zoom. |
double |
getScaleFactor()
Returns the current zoom scale factor. |
Rectangle2D |
getVisibleArea()
Returns the logical coordinates of the region visible on the screen. |
protected Rectangle |
getZoomableBounds(Rectangle bounds)
Returns the bounding box (in pixel coordinates) of the zoomable area. |
boolean |
hasPreferredArea()
Indicates whether the logical coordinates of a region have been defined. |
boolean |
isMagnifierEnabled()
Indicates whether or not the magnifying glass is allowed to be displayed on this component. |
boolean |
isMagnifierVisible()
Indicates whether or not the magnifying glass is visible. |
boolean |
isPaintingWhileAdjusting()
Indicates whether or not this ZoomPane object should be repainted when the user
moves the scrollbar slider. |
protected void |
mouseSelectionPerformed(Shape area)
Method called automatically after the user selects an area with the mouse. |
protected void |
paintComponent(Graphics graphics)
Paints this component. |
protected abstract void |
paintComponent(Graphics2D graphics)
Paints this component. |
protected void |
paintMagnifier(Graphics2D graphics)
Paints the magnifying glass. |
protected void |
printComponent(Graphics graphics)
Prints this component. |
protected void |
printComponent(Graphics2D graphics)
Prints this component. |
void |
removeZoomChangeListener(ZoomChangeListener listener)
Removes an object from the list of objects interested in being notified about zoom changes. |
void |
repaint(long tm,
int x,
int y,
int width,
int height)
Declares that a part of this pane needs to be repainted. |
void |
reset()
Reinitializes the affine transform zoom in order to cancel any zoom, rotation or
translation. |
protected void |
reset(Rectangle zoomableBounds,
boolean yAxisUpward)
Reinitializes the affine transform zoom in order to cancel any zoom, rotation or
translation. |
void |
scrollRectToVisible(Rectangle rect)
Modifies the position in pixels of the visible part of ZoomPane . |
void |
setMagnifierBorder(Paint color)
Set the color of the magnifying glass's border. |
void |
setMagnifierEnabled(boolean enabled)
Specifies whether or not the magnifying glass is allowed to be displayed on this component. |
void |
setMagnifierGlass(Paint color)
Set the color with which to tint magnifying glass. |
void |
setMagnifierVisible(boolean visible)
Displays or hides the magnifying glass. |
void |
setPaintingWhileAdjusting(boolean flag)
Defines whether or not this ZoomPane object should repaint the map when the user
moves the scrollbar slider. |
void |
setPreferredArea(Rectangle2D area)
Specifies the logical coordinates of the region that we want to see displayed the first time that ZoomPane appears on the screen. |
protected void |
setResetPolicy(boolean fill)
Set the policy for the zoom when the content is initially drawn or when the user resets the zoom. |
void |
setVisibleArea(Rectangle2D logicalBounds)
Defines the limits of the visible part, in logical coordinates. |
void |
tieModels(BoundedRangeModel x,
BoundedRangeModel y)
Synchronises the position and the range of the models x and y with the position of the zoom. |
void |
transform(AffineTransform change)
Changes the zoom by applying an affine transform. |
void |
transformPixels(AffineTransform change)
Changes the zoom by applying an affine transform. |
void |
untieModels(BoundedRangeModel x,
BoundedRangeModel y)
Cancels the synchronisation between the specified x and y models and the zoom of this ZoomPane object. |
void |
updateUI()
Informs ZoomPane that the GUI has changed. |
Methods inherited from class Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int SCALE_X
public static final int SCALE_Y
public static final int UNIFORM_SCALE
SCALE_X
and SCALE_Y
. The inverse, however, (SCALE_X
|SCALE_Y
)
doesn't imply UNIFORM_SCALE
.
public static final int TRANSLATE_X
public static final int TRANSLATE_Y
public static final int ROTATE
public static final int RESET
reset()
.
public static final int DEFAULT_ZOOM
SCALE_X
and SCALE_Y
flags is not also specified.
protected final AffineTransform zoom
Graphics2D.transform
(zoom)
.
Constructor Detail |
---|
public ZoomPane(int type) throws IllegalArgumentException
ZoomPane
.
type
- Allowed zoom type. It can be a bitwise combination of the following constants:
SCALE_X
, SCALE_Y
, UNIFORM_SCALE
, TRANSLATE_X
,
TRANSLATE_Y
, ROTATE
, RESET
and DEFAULT_ZOOM
.
IllegalArgumentException
- If type
is invalid.Method Detail |
---|
public void reset()
zoom
in order to cancel any zoom, rotation or
translation. The default implementation initializes the affine transform zoom
in
order to make the y axis point upwards and make the whole of the region covered
by the getPreferredArea()
logical coordinates appear in the panel.
Note: for the derived classes: reset()
is the only method of ZoomPane
which doesn't have to pass through transform(AffineTransform)
to modify the zoom.
This exception is necessary to avoid falling into an infinite loop.
protected final void reset(Rectangle zoomableBounds, boolean yAxisUpward)
zoom
in order to cancel any zoom, rotation or
translation. The argument yAxisUpward
indicates whether the y axis should
point upwards. The value false
lets it point downwards. This method is offered
for convenience sake for derived classes which want to redefine reset()
.
zoomableBounds
- Coordinates, in pixels, of the screen space in which to draw.
This argument will usually be
getZoomableBounds
(null)
.yAxisUpward
- true
if the y axis should point upwards rather than
downwards.protected void setResetPolicy(boolean fill)
true
means that the panel should initially be completely filled, even if
the content partially falls outside the panel's bounds. Value false
means that the
full content should appear in the panel, even if some space is not used. Default value is
false
.
public abstract Rectangle2D getArea()
ZoomPane
. For example, if this ZoomPane
is to display
a geographic map, then this method should return the map's bounds in degrees of latitude
and longitude. This bounding box is completely independent of any current zoom setting and
will change only if the content changes.
ZoomPane
. If this bounding box is unknown, then this method
can return null
(but this is not recommended).public final boolean hasPreferredArea()
true
if setPreferredArea(java.awt.geom.Rectangle2D)
has been called with a non null argument.
public final Rectangle2D getPreferredArea()
ZoomPane
appears on the screen. This region will also be displayed each time
the method {link #reset} is called. The default implementation goes as follows:
setPreferredArea(java.awt.geom.Rectangle2D)
, this region will be returned.getArea()
will be returned.
null
if these coordinates are unknown.public final void setPreferredArea(Rectangle2D area)
ZoomPane
appears on the screen. This region will also be displayed the first
time that the method {link #reset} is called.
public final Rectangle2D getVisibleArea()
public void setVisibleArea(Rectangle2D logicalBounds) throws IllegalArgumentException
zoom
contains
a rotation, this rotation will not be modified.
logicalBounds
- Logical coordinates of the region to be displayed.
IllegalArgumentException
- if source
is empty.protected Rectangle getZoomableBounds(Rectangle bounds)
JComponent.getBounds(Rectangle)
, except that the zoomable area may be smaller than the whole
widget area. For example, a chart needs to keep some space for axes around the zoomable area.
Another difference is that pixel coordinates are relative to the widget, i.e. the (0,0)
coordinate lies on the ZoomPane
upper left corner, no matter what its location on
screen.
ZoomPane
invokes getZoomableBounds
when it needs to set up an initial
zoom
value. Subclasses should also set the clip area to this bounding box in their
paintComponent(Graphics2D)
method before setting the graphics transform.
For example:
graphics.clip(getZoomableBounds(null)); graphics.transform(zoom
);
bounds
- An optional pre-allocated rectangle, or null
to create a new one. This
argument is useful if the caller wants to avoid allocating a new object on the heap.
ZoomPane
widget.protected Dimension getDefaultSize()
JComponent.getPreferredSize()
if no preferred size has been explicitly set with
JComponent.setPreferredSize(java.awt.Dimension)
.
protected Dimension2D getPreferredPixelSize()
getArea()
.
public double getScaleFactor()
getArea()
are
expressed in metres). Scale factors for X and Y axes can be computed separately using the
following equations:
![]() |
![]() |
ZoomPane
has
been constructed with the UNIFORM_SCALE
type.
public void transform(AffineTransform change)
change
transform
must express a change in logical units, for example, a translation in metres. This method is
conceptually similar to the following code:
zoom
.concatenate
(change);fireZoomChanged
(change);repaint
(getZoomableBounds
(null));
change
- The zoom change, as an affine transform in logical coordinates. If
change
is the identity transform, then this method does nothing and
listeners are not notified.public void transformPixels(AffineTransform change)
change
transform
must express a change in pixel units, for example, a scrolling of 6 pixels toward right. This
method is conceptually similar to the following code:
zoom
.preConcatenate
(change);fireZoomChanged
(change translated in logical units);repaint
(getZoomableBounds
(null));
change
- The zoom change, as an affine transform in pixel coordinates. If
change
is the identity transform, then this method does nothing
and listeners are not notified.public void addZoomChangeListener(ZoomChangeListener listener)
public void removeZoomChangeListener(ZoomChangeListener listener)
public void addMouseListener(MouseListener listener)
addMouseListener
in class Component
protected void fireZoomChanged(AffineTransform change)
addZoomChangeListener(org.geotools.gui.swing.event.ZoomChangeListener)
method will be notified of the change as soon as possible.
change
- Affine transform which represents the change in the zoom. That is
oldZoom
and newZoom
are the affine transforms of the old and new zoom
respectively. Therefore, the relation
newZoom=oldZoom.concatenate
(change)
must be respected (to within rounding errors). Note: This method can modify
change
to combine several consecutive calls of fireZoomChanged
in a single transformation.protected void mouseSelectionPerformed(Shape area)
area
. Derived classes can redefine this method
in order to carry out another action.
area
- Area selected by the user, in logical coordinates.protected Shape getMouseSelectionShape(Point2D point)
Ellipse2D
vs Rectangle2D
) and any of its
parameters not related to its position (e.g. corner rounding in a rectangle
RoundRectangle2D
).
The returned shape will generally be from a class derived from
RectangularShape
, but can also be from the class
Line2D
. Any other class risks firing a
ClassCastException
at execution.
The default implementation always returns a Rectangle2D
object.
point
- Logical coordinates of the mouse at the moment the button is pressed. This
information can be used by derived classes that wish to consider the mouse position
before choosing a geometric shape.
null
to indicate that
we do not want to select with the mouse.public boolean isMagnifierEnabled()
public void setMagnifierEnabled(boolean enabled)
false
will hide the magnifying glass, delete the
choice "Display magnifying glass" from the contextual menu and lead to all calls to
setMagnifierVisible
(true)
being ignored.
public boolean isMagnifierVisible()
setMagnifierVisible(boolean)
to make it appear.
public void setMagnifierVisible(boolean visible)
true
, the magnifying glass will appear at the
centre of the window.
public Paint getMagnifierGlass()
public void setMagnifierGlass(Paint color)
public Paint getMagnifierBorder()
public void setMagnifierBorder(Paint color)
public final void correctApparentPixelPosition(Point2D point)
point
is outside the magnifier, then this method do
nothing.point
in such a way that it contains the position that the exact same pixel
would have in the absence of magnifier.
correctApparentPixelPosition
in interface DeformableViewer
point
- In input, a pixel's coordinate as it appears on the screen. In output, the
coordinate that the same pixel would have if the magnifier wasn't presents.public void buildNavigationMenu(JMenu menu)
protected JPopupMenu getPopupMenu(MouseEvent event)
event
- Mouse event. This object contains the mouse coordinates
in geographic coordinates (as well as pixel coordinates).
null
to avoid displaying the menu.protected JPopupMenu getMagnifierMenu(MouseEvent event)
event
- Mouse event containing amongst others, the mouse position.
null
to avoid displaying the menu.public JComponent createScrollPane()
ZoomPane
with the scrollbars.
public void tieModels(BoundedRangeModel x, BoundedRangeModel y)
x
- Model of the horizontal scrollbar or null
if there isn't one.y
- Model of the vertical scrollbar or null
if there isn't one.public void untieModels(BoundedRangeModel x, BoundedRangeModel y)
ZoomPane
object. The ChangeListener
and
ZoomChangeListener
objects that were created are deleted.
x
- Model of the horizontal scrollbar or null
if there isn't one.y
- Model of the vertical scrollbar or null
if there isn't one.public void scrollRectToVisible(Rectangle rect)
ZoomPane
. viewSize
is the size ZoomPane
would be (in pixels) if its visible surface covered the whole
of the getArea()
region with the current zoom (Note: viewSize
can be obtained
by JComponent.getPreferredSize()
if JComponent.setPreferredSize(java.awt.Dimension)
hasn't been called with a non-null
value). Therefore, by definition, the region getArea()
converted into pixel space
would give the rectangle
bounds=Rectangle(0, 0, ,viewSize.width, ,viewSize.height)
.
This scrollRectToVisible
method allows us to define the sub-region of bounds
which must appear in the ZoomPane
window.
scrollRectToVisible
in class JComponent
public boolean isPaintingWhileAdjusting()
ZoomPane
object should be repainted when the user
moves the scrollbar slider. The scrollbars (or other models) involved are those which have
been synchronised with this ZoomPane
object through the tieModels(javax.swing.BoundedRangeModel, javax.swing.BoundedRangeModel)
method.
The default value is false
, which means that ZoomPane
will wait until the
user releases the slider before repainting.
public void setPaintingWhileAdjusting(boolean flag)
ZoomPane
object should repaint the map when the user
moves the scrollbar slider. A fast computer is recommended if this flag is to be set to
true
.
public void repaint(long tm, int x, int y, int width, int height)
repaint
in class JComponent
protected void paintMagnifier(Graphics2D graphics)
paintComponent(Graphics2D)
if a magnifying glass is visible.
protected abstract void paintComponent(Graphics2D graphics)
ZoomPane
content. For most implementations, the first line in this method will be
graphics.transform(zoom
)
.
protected void printComponent(Graphics2D graphics)
paintComponent(Graphics2D)
.
protected final void paintComponent(Graphics graphics)
paintComponent(Graphics2D)
instead.
paintComponent
in class JComponent
protected final void printComponent(Graphics graphics)
printComponent(Graphics2D)
instead.
printComponent
in class JComponent
public Insets getInsets(Insets insets)
super.getInsets(insets)
,
but accepts a null argument. This method can be redefined if it is necessary to perform zooms
on a part of the graphic rather than the whole thing.
getInsets
in class JComponent
public final Insets getInsets()
getInsets(Insets)
.
getInsets
in class JComponent
public void updateUI()
ZoomPane
that the GUI has changed.
The user doesn't have to call this method directly.
updateUI
in class JComponent
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |