Package com.luciad.gui.swing.navigationcontrols

Class 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:

  • Field Details

    • 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:

    • 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:

  • Constructor Details

    • 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 Details

    • 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:

    • 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

      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

      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:

    • 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

      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:

    • 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

      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:

    • 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.