com.luciad.gui.swing.navigationcontrols

LuciadLightspeedClass ALcdCompassNavigationControl

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JPanel

com.luciad.gui.swing.navigationcontrols.ALcdCompassNavigationControl

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible

Direct Known Subclasses:

TLcdGXYCompassNavigationControl, TLspCompassNavigationControl

public abstract class ALcdCompassNavigationControl
extends JPanel

This class implements the compass (usually the upper part) of the navigation controls. It offers two interactive components:

• a draggable rotation indicator, that can be used to change an angle.
• a central area that can be used to change a two dimensional point. This point will correspond with the position of the mouse cursor ( or an other input method ) with respect to the center of the component.

These values can be retrieved using the methods getAngle() and getPoint(). They are updated based on received mouse events. You can drag the outer ring to change the angle, and pressing or dragging the mouse anywhere else in the component will change the point.

Usually implementations will want to know when one of these values is changed internally, as a consequence of mouse events directly on the component. A subclass therefore has to implement certain abstract methods. For the angle, this is the method angleChanged(). A call to this method will notify the implementing class that it may use a new angle value (retrieved with getAngle()) to interact with a view (e.g. its rotation) or other object. Note however that the angle can also be changed by subclasses using the method setAngle(double). Subclasses can use this method to adjust the angle when the mouse is not interacting with this component. This will typically be used to make sure that the compass always points north on a rotation capable map.

As for the point, it is only available after a mouse pressed event is received and before a mouse released event is received. These events trigger calls to the abstract methods interactionStarted() and interactionTerminated() respectively. In this way they notify the implementing class that between these calls, the method getPoint() will return a point that can be used to interact with a view or other object. Usually this point will be used to pan or rotate a view. A call to startInteraction can for instance start a timer that will periodically check the value returned by getPoint to pan the view until the timer is stopped by a call to endInteraction .

The appearance of this component is specified by a number of images. Furthermore the appearance can be changed at runtime. The method setEnabled(boolean) can be used to toggle between an active and an inactive appearance. By default the active appearance is only used when the mouse hovers over the component. The active/inactive appearance is usually shared with a few other (navigation control) components. See TLcdMouseOverGroup for more details.

The exact appearance is specified by the following images in png format:

• compass_arrows_inactive.png: the arrows that indicate the compass direction, when the navigation panel is inactive.
• compass_circles_inactive.png: The center of the panel when the navigation panel is inactive. This image will be used when the panel is not in pan mode.
• compass_arrows.png: the arrows that indicate the compass direction, when the navigation panel is active
• compass_circles.png: The center of the panel when the navigation panel is active. This image will be used when the panel is not in pan mode.
• compass_indicator_selected.png: the north arrow when the mouse hovers over it.
• compass_direction.png: the direction indicator when pressing or dragging the mouse over the panel.
• compass_ring_inactive.png: the draggable rotation ring when it isn't used.
• compass_ring.png: the draggable rotation ring when it is used.

All the images should be square and should have the same dimensions. The dimension of the images will also be the dimension of the component. Also keep in mind that 'compass_arrows_inactive.png', 'compass_arrows.png', 'compass_indicator_selected.png' and 'compass_direction.png' will be rotated around the center of the images.

Below you can see what the compass control looks like, using the default set of images. The two images at the right are used when the compass pans the view instead of looking around.

Since:

10.0

See Also:

Serialized Form

Nested Class Summary

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	COMPASS_COMPONENT_DIR Default name of the subfolder in the navigation controls image folder containing all compass panel images.
static String	COMPASSPAN_COMPONENT_DIR Default name of the subfolder in the navigation controls image folder containing all compass panel images when the compass panel will be used for panning (in 2D for example).

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
ALcdCompassNavigationControl(String aImagePath) A constructor for the compass component.

Method Summary

Modifier and Type	Method and Description
protected abstract void	angleChanged() This method is called whenever the angle has been changed by direct interaction with the component (received mouse events).
protected double	getAngle() This method returns the rotation angle currently used to draw rotating parts of the component.
Cursor	getCursor()
ILcdMagneticNorthMap	getMagneticNorthMap() Returns the magnetic north map to be used to point to the magnetic north.
Dimension	getMaximumSize() Returns the dimension specified by the images used.
Dimension	getMinimumSize() Returns the dimension specified by the images used.
protected Point2D.Double	getPoint() This method returns a point that represents where the mouse is located over the panel.
Dimension	getPreferredSize() Returns the dimension specified by the images used.
String	getRingToolTipText() Returns the tool tip string that has been set with setRingToolTipText.
String	getToolTipText(MouseEvent event)
String	getUpArrowToolTipText() Returns the tool tip string that has been set with setUpArrowToolTipText.
protected abstract void	interactionStarted() This method will be called when the mouse starts interacting with the panel (except when it's interacting with the draggable rotation ring).
protected abstract void	interactionTerminated() This method will be called when the mouse stops interacting with the panel.
protected void	setAngle(double aAngle) Sets the rotation angle of the rotating parts of the component.
void	setEnabled(boolean enabled)
void	setMagneticNorthMap(ILcdMagneticNorthMap aMagneticNorthMap) Lets the compass point to the magnetic north instead of true north, using the given magnetic north map.
void	setRingToolTipText(String aRingToolTipText) Registers the text to display in a tool tip when the cursor lingers over the up arrow of the this compass navigation control.
void	setUpArrowToolTipText(String aUpArrowToolTipText) Registers the text to display in a tool tip when the cursor lingers over the up arrow of the this compass navigation control.

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, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, 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, 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, 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

COMPASS_COMPONENT_DIR

public static final String COMPASS_COMPONENT_DIR

Default name of the subfolder in the navigation controls image folder containing all compass panel images.

See Also:

Constant Field Values

COMPASSPAN_COMPONENT_DIR

public static final String COMPASSPAN_COMPONENT_DIR

Default name of the subfolder in the navigation controls image folder containing all compass panel images when the compass panel will be used for panning (in 2D for example). The default images show a hand instead of an eye then.

See Also:

Constant Field Values

Constructor Detail

ALcdCompassNavigationControl

public ALcdCompassNavigationControl(String aImagePath)
                             throws IOException

A constructor for the compass component. The constructor also loads the necessary images and will initialize all the subcomponents of the panel.

The default image path is usually the path to the root folder of the navigation controls + COMPASS_COMPONENT_DIR or COMPASSPAN_COMPONENT_DIR. The directory COMPASSPAN_COMPONENT_DIR should contain a set of images to be used when the compass will be able to pan the view. These constants can be used by factory methods to create a complete set of navigation controls with a single path to a root folder.

Parameters:

aImagePath - The (relative or absolute) path to the directory where the images are stored. For relative paths, the classpath and the working directory are searched.

Throws:

IOException - when one of the necessary images is missing.

Method Detail

setEnabled

public void setEnabled(boolean enabled)

Overrides:

setEnabled in class JComponent

getCursor

public Cursor getCursor()

Overrides:

getCursor in class Component

setMagneticNorthMap

public void setMagneticNorthMap(ILcdMagneticNorthMap aMagneticNorthMap)

Lets the compass point to the magnetic north instead of true north, using the given magnetic north map.

Parameters:

aMagneticNorthMap - the map to use. If null, the compass will point to the true north

getMagneticNorthMap

public ILcdMagneticNorthMap getMagneticNorthMap()

Returns the magnetic north map to be used to point to the magnetic north.

Returns:

the map to use. If null, the compass will point to the true north

getAngle

protected double getAngle()

This method returns the rotation angle currently used to draw rotating parts of the component.

Returns:

The angle that indicates how far the compass is rotated. A return value of zero means the compass points straight up. A positive value means the compass is rotated clockwise (like a regular compass) over an angle equal to the value (in radians).

setAngle

protected void setAngle(double aAngle)

Sets the rotation angle of the rotating parts of the component. Typically, the compass bearing is the inverse direction of this angle (i.e. bearing = -angle). This method is called internally in response to mouse events. Subclasses should call this method whenever the compass bearing changes, for instance during panning or if the view has been rotated by another controller.
Refer to the angleChanged() method to update the view if the user interacts with the compass.

Parameters:

aAngle - the angle to draw the rotating parts of the component, positive clockwise from 12 o'clock, in radians

angleChanged

protected abstract void angleChanged()

This method is called whenever the angle has been changed by direct interaction with the component (received mouse events). Implementations of this method should apply the angle (typically to an instance of ILcdView). The method should not be called by subclasses.

See Also:

getAngle()

getPoint

protected Point2D.Double getPoint()

This method returns a point that represents where the mouse is located over the panel. It corresponds with the location of the mouse relative to the center of the component, but scaled using the Dimension of the panel, so the resulting X and Y values are between 1 and -1. Note: you should only use this method between a call to interactionStarted() and a call to interactionTerminated(). It will not return usable values at any other time.

Returns:

a point representing the relative position of the mouse with respect to the center of the panel.

See Also:

interactionStarted(), interactionTerminated()

interactionStarted

protected abstract void interactionStarted()

This method will be called when the mouse starts interacting with the panel (except when it's interacting with the draggable rotation ring). Between a call to this method and a call to interactionTerminated() the method getPoint() will return a point that can be used to interact with an object.

See Also:

interactionTerminated(), getPoint()

interactionTerminated

protected abstract void interactionTerminated()

This method will be called when the mouse stops interacting with the panel. Between a call to interactionStarted() and a call to this method, the method getPoint() will return a point that can be used to interact with an object.

See Also:

interactionStarted(), getPoint()

getRingToolTipText

public String getRingToolTipText()

Returns the tool tip string that has been set with setRingToolTipText.

Returns:

the text of the tool tip for the part of the compass navigation control covered by the rotation ring.

See Also:

setRingToolTipText(String)

setRingToolTipText

public void setRingToolTipText(String aRingToolTipText)

Registers the text to display in a tool tip when the cursor lingers over the up arrow of the this compass navigation control.

Parameters:

aRingToolTipText - the text to display in a tool tip over the up arrow, or null if no specific tool tip should be shown.

See Also:

getRingToolTipText()

getUpArrowToolTipText

public String getUpArrowToolTipText()

Returns the tool tip string that has been set with setUpArrowToolTipText.

Returns:

the text of the tool tip for the part of the compass navigation control covered by the up arrow.

See Also:

setUpArrowToolTipText(String)

setUpArrowToolTipText

public void setUpArrowToolTipText(String aUpArrowToolTipText)

Registers the text to display in a tool tip when the cursor lingers over the up arrow of the this compass navigation control.

Parameters:

aUpArrowToolTipText - the text to display in a tool tip over the up arrow, or null if no specific tool tip should be shown.

See Also:

getUpArrowToolTipText()

getToolTipText

public String getToolTipText(MouseEvent event)

Overrides:

getToolTipText in class JComponent

getPreferredSize

public Dimension getPreferredSize()

Returns the dimension specified by the images used.

Overrides:

getPreferredSize in class JComponent

Returns:

the size of the images this panel is a based on.

getMinimumSize

public Dimension getMinimumSize()

Returns the dimension specified by the images used.

Overrides:

getMinimumSize in class JComponent

Returns:

the size of the images this panel is a based on.

getMaximumSize

public Dimension getMaximumSize()

Returns the dimension specified by the images used.

Overrides:

getMaximumSize in class JComponent

Returns:

the size of the images this panel is based on.